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About This Document 



The Device Driver Interface/Driver- Kernel Interface Reference Manual provides 
reference information needed to write device drivers in the UNIX System V 
Release 4 environment. It describes two device driver interface specifications: 
the Device Driver Interface (DDI) and the Driver- Kernel Interface (DKI). 
Drivers written to conform to one or both of these interfaces are more likely to 
be portable to other environments. DDI and DKI address different aspects of 
the compatibility problem — ^their differences are summarized in Figure 1-1. 



Figure 1-1: Scope of DDI and DKI 
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Each box in Figure 1-1 represents a different set of interfaces. The "DDI only" 
set (indicated throughout this manual with the DjcD cross-reference code) are 
processor specific and are intended to be supported beyond Release 4.0. The 
DDI described in this manual is specific to the porting base, the 3B2 computer. 
The "DKI only" set (D;cK cross-reference code) are processor independent, but 
are not guaranteed to be supported in the next release. 

Most of the routines, functions, and structures described in this manual are part 
of both DDI and DKI (cross-referenced by DxDK). As Figure 1-1 shows, drivers 
written to conform to both interfaces are portable to all AT&T computers sup- 
porting UNIX System V Release 4, and they will be compatible through and 
beyond Release 4. To understand more completely what is meant by "portable" 
and "compatible" for DDI and DKI, the scope of each interface must be more 
thoroughly explained. 
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The goals of DDI and DKI overlap, and are not in any way mutually exclusive. 
That is, a driver may be written to conform to both interfaces, increasing the 
chances that driver code can be ported and can remain compatible with future 
releases of the operating system. 

Porting 

Software is usually considered portable if it can be adapted to run in a different 
environment more cheaply than it can be rewritten. The new environment may 
include a different processor, operating system, and even the language in which 
the program is written, if a language translator is available. More often, how- 
ever, software is ported between environments that share an operating system, 
processor, and source language. The source code is modified to accommodate 
the differences in compilers or processors or releases of the operating system. 

In the past, device drivers did not port easily for one or more of the following 
reasons: 

■ To enhance functionality, members had been added to kernel data struc- 
tures accessed by drivers, or the sizes of existing members had been 
redefined. 

■ The calling or return syntax of kernel functions had changed. 

■ Driver developers did not use existing kernel functions where available, 
or relied on undocumented side effects that were not maintained in the 
next release. 

■ Processor-specific code had been scattered throughout the driver when it 
could have been isolated. 

Operating systems are periodically reissued to customers as a way to improve 
performance, fix bugs, and add new features. This is probably the most com- 
mon threat to compatibility encountered by developers responsible for maintain- 
ing software. Another common problem is upgrading hardware. As new 
hardware is developed, customers occasionally decide to upgrade to faster, 
more capable computers of the same family. Although they may run the same 
Of>erating system as those being replaced, processor-specific code may prevent 
the software from porting. 
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Scope of Interfaces 

Although application programs have all of the porting problems mentioned, 
developers attempting to port device drivers have special challenges. Before 
describing the differences between DDI and DKI, it is necessary to understand 
the position of device drivers in UNIX systems. 

Device drivers are kernel modules that control data transferred to and received 
from peripheral devices. Although drivers are configured into a UNIX system as 
part of the kernel, they are developed independently from the rest of the kernel. 
If the goal of achieving complete freedom in modifying the kernel is to be 
reconciled with the goal of binary compatibility with existing drivers, the 
interaction between drivers and the kernel must be rigorously regulated. This 
driver/kemel service interface is the most important of the three distinguishable 
interfaces for a driver, summarized as follows: 

■ Driver- Kernel. I/O System calls result in calls to driver entry point rou- 
tines. These make up the kemel-to-driver part of the service interface, 
described in Section 2 of this manual. Drivers may call any of the func- 
tions described in Section 3. These are the driver-to-kernel part of the 
interface. 

■ Driver- Hardware. All drivers (except software drivers) must include an 
interrupt handling entry point, and may also perform direct memory 
access (DMA). These, and other hardware-specific interactions make up 
the driver/hardware interface. 

■ Driver- Boot/Configuration Software. At boot time, the existence of a 
driver is made known to the system through information in system files, 
enabling the system to include the driver. The interaction between the 
driver and the boot and configuration software is the third interface affect- 
ing drivers. 

Scope of the Device Driver Interface (DDI) 

The primary goal of DDI is to facilitate both source and binary portability across 
successive releases of UNIX System V on a particular machine. Implicit in this 
goal is an important fact. Although there is only one DKI, each processor pro- 
duct has its own DDI. Therefore, if a driver is ever to be ported to different 
hardware, special attention must be paid to the machine-specific routines that 
make up the 'ODI only part of a driver. These include but are not confined to 
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the driver/hardware interface (as described in the previous section). Some 
processor-specific functionality also may belong to the driver/kernel interface, 
and may not be easy to locate. 

To achieve the goal of source and binary compatibility, the functions, routines, 
and structures specified in a DDI must be used according to these rules. 

■ Drivers cannot access system state structure (for example, u and sysinf o) 
directly. 

■ For structures external to the driver that may be accessed directly, only 
the utility functions provided in Section 3 of this manual should be used. 
More generally, these functions should be used wherever possible. 

■ The header file ddi . h must be included at the end of the list of header 
files. This header file "undefines" several macros that are reimplemented 
as functions. 



Scope Of the Driver- Kernel Interface (DKI) 

As its name implies, the DKI (Driver- Kernel Interface) is a defined service inter- 
face for the entry point routines and utility functions specified for communica- 
tion between the driver and kernel. It does not encompass the driver/hardware 
or the driver/boot software interface. 

Information is exchanged between the driver and kernel in the form of data 
structures. The DKI specifies the contents of these structures as well as the cal- 
ling and return syntax of the entry points and utility functions. 

The intent of DKI is to promote source portability across implementations of 
UNIX System V on different machines, and applies only to System V Release 4. 
Because DKI applies only to the driver/kernel interface, it must be understood 
that the sections of driver code affecting the hardware and boot/ configuration 
interfaces may need to be rewritten, and should be isolated in subroutines as 
much as possible. 
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|||p|| Certain interfaces documented in the DKI are not part of the DDI. Driver 
NOTE writers should be aware that the use of these interfaces is not guaranteed to 
be supported beyond System V Release 4. 



Interface Members 

As noted before, most entry points (Section 2), functions (Section 3), and struc- 
tures (Section 4) described in this manual belong to both DDI and DKI. Table 
1-1 lists the those that are exclusive either to DDI or DKI. 



Table 1-1: Exclusive Entry Points, Functions, and Structures 



DDI only DKI only 


Section 2 


initV intr size, start 


seginap, mmap 


Section 3 


dinaj>ageio, etoimajor, 
geteinajor, geteminor, 
getvec, hdeeqd, hdelog, 
itoemajor, kvtophys, 
physiock, vtop 


hat__getkpf num 


Section 4 


hdedata 


None 



Audience 

This manual is for experienced C programmers responsible for creating, modify- 
ing, or maintaining drivers that run on AT&T UNIX System V Release 4 and 
beyond. It assumes that the reader is familiar with UNIX system internals and 
the advanced capabilities of the C Progrannming Language. See the "Related 
Learning Materials" section for a list of available AT&T documents and courses. 
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How to Use This Document 

This manual is organized into four sections and two appendixes: 

■ "Section 1: Introduction" introduces the DDI, DKI, and other driver inter- 
faces, lists the notational conventions used in this document, and lists 
related courses and documents. 

■ "Section 2: Driver Entry Points" contains reference pages for all driver 
entry point routines. 

■ "Section 3: Kernel Functions" contains reference pages for all driver func- 
tions used in DDI/DKI drivers. 

■ "Section 4: Data Structures" contains reference pages for structures used 
in DDI/DKI drivers. 

■ "Appendix A: Error Codes" contains a list of the error codes that are 
appropriate for use in DDI/DKI drivers. 

■ "Appendix B: Migration from Release 3.2 to Release 4.0" describes the 
changes to DDI/DKI between Release 3.2 and Release 4.0 of System V. 
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Driver reference manual pages are similar to those in the Programmer's Reference 
Manual, with the page name followed by a section number in parentheses. All 
driver reference manual entries begin with a "D" to distinguish them as driver 
reference pages. 

Currently, the reference pages for the different interfaces are published in 
separate volumes. Each manual contains three sections: 

D2 driver entry points 

D3 kernel functions used by drivers 

D4 system data structures accessed by drivers 

Each section number is suffixed with a letter indicating the interfaces covered. 
The suffixes used are: 

D Device Driver Interface (DDI) 

K Driver- Kernel Interface (DKI) 

DK DDI and DKI 

I SCSI Device Interface (SDI) 

P Portable Device Interface (PDI) 

X Block and Character Interface (BCD 

For example, open(D2DK) refers to the open entry point routine for a driver, not 
to the open(2) system call documented in the Programmer's Reference Manual. 
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Table 1-2 lists the textual conventions used in this book. 



Table 1-2: Textual Conventions Used In This Book 



Item 


Style 


Example 


C Reserved Words 


Constant Width 


typedef 


C typedef Declarations 


Constant Width 


caddr_t 


Driver Routines 


Constant Width 


open routine 


Error Values 


Constant Width 


EINTR 


File Names 


Constant Width 


sys/conf .h 


Flag Names 


Constant Width 


BJWRITE 


Kernel Macros 


Constant Width 


minor 


Kernel Functions 


Constant Width 


ttopen 


Kernel Function Arguments 


Italics 


bp 


Structure Members 


Constant Width 


b_addr 


Structure Names 


Constant Width 


buf structure 


Symbolic Constants 


Constant Width 


NULL 


System Calls 


Constant Width 


ioctl(2) 


C Library Calls 


Constant Width 


print f(3S) 


Shell Commands 


Constant Width 


layers(l) 


User-Defined Variable 


Italics 


preftxclose 
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AT&T provides a number of documents and courses to support users of our 
systems. For a listing see: 

KT&T Computer Systems Documentation Catalog (300-000) 
AT&T Computer Systems Education Catalog (300-002) 



Documentation 

Most documents listed here are available from the AT&T Customer Information 
Center. Refer to the six-digit select code (in parentheses, following the docu- 
ment title) when ordering. 

If ordering by telephone, use the following numbers: 

1-800-432-6600 (toll free within the continental United States) 
1-317-352-8557 (outside the continental United States) 

In addition to AT&T documents, the following list includes some commercially 
available documents that are relevant. 

Driver Development 

The umx System V and V/386, Release 3, Block and Character Interface (BCD 
Development Gwfde(307-191) discusses driver development concepts, debugging, 
performance, installation, and other related driver topics for UNIX System V 
Releases. 

The UMX System V and V/386, Release 3, Block and Character Interface (BCD Driver 
Reference Manual (307-192) includes UNIX System V Rlease 3 reference material 
to be used in conjunction with the above manual. It describes driver entry point 
routines (Section D2X), kernel-level functions used in BCI drivers (Section D3X), 
and data structures accessed by BQ drivers (Section D4X). 

The UNIX System V PDI Driver Design Reference Manual (305-014) defines the ker- 
nel functions and data structures used for Portable Driver Interface (PDI) 
drivers. 

The UNIX System V SCSI Driver Interface (SDI), Driver Design Reference Manual 
(305-009) defines the kernel functions and data structures used for SDI drivers. 
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STREAMS 

The Programmer's Guide: STREAMS tells how to write drivers and access devices 
that use the STREAMS driver interface for character access. 

C Programming Language and General Programming 

Bentley, Jon Louis, Writing Efficient Programs (320-004), Englewood Chffs, New 
Jersey: Prentice-Hall, 1982, gives hints for coding practices that improve process 
performance. Many of these ideas can be applied to driver code. 

Kernighan, B. and D. Ritchie, C Programming Language, Second Edition (307-136), 
Englewood Cliffs, New Jersey: Prentice-Hall, 1988, defines the functions, struc- 
tures, and interfaces of the C Programming Language. A short tutorial is 
included. 

Lapin, J. E., Portable C and UNIX System Programming, Englewood Cliffs, New 
Jersey: Prentice-Hall, 1987, discusses how to maximize the portability of C 
language programs. 

The Programmer's Guide: Networking Interfaces provides detailed information, 
with examples, on the Section 3N library that comprises the UNIX system Tran- 
sport Level Interface (TLI). 

The Programmer's Guide: ANSI C and Programming Support Tools includes instruc- 
tions on using a number of UNIX utilities, including nake and SCCS. 

Assembly Language 

The AT&T 3B2/3B5I3B15 Computers Assembly Language Programming Manual 
(305-000) describes the Assembly Language instructions used by AT&T 3B2, 
3B15 and 3B4000 computers. 

WE 32100 Microprocessor Information Manual, Maxicomputing in Microspace (307- 
730) introduces the WE 32100 microprocessor and summarizes its available sup- 
port products. 
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Operating System 

Bach, Maurice J., Design of the UNIX Operating System (320-044), Englewood 
Cliffs, New Jersey: Prentice-Hall, 1986, discusses the internals of the UNIX 
operating system, and includes an explanation of how drivers relate to the rest 
of the kernel. 

The UNIX System V reference manuals are the standard reference materials for 
the UNIX operating system. This information is organized into three books, 
published separately for each system: 

■ V^e System Mministrato/s Reference Manml inc^^ 

administrative commands (Section IM), special device files (Section 7), and 
system-specific maintenance commands (Section 8). 

■ The Programmer's Reference Manual includes information on programming 
corrimands (Section 1), system calls (Section 2), library routines (Section 3), 
file formats (Section 4), and miscellaneous topics (Section 5). 

■ The User's Reference Manual includes information on UNIX system user- 
level commands (Section 1). 

Software Packaging 

The Programmer's Guide: System Services and Application Packaging Tools describes 
how to write the scripts necessary to install a driver (or other software) under 
the System Administration utility. 

Training 

The following courses are of particular interest to driver writers. To register for 
a class: 

■ Within the continental United States, call 1-800-TRAINER. 

■ Within Canada, call 1-800-22M647. 

■ Outside the continental United States, call 1-201-953-7554. 
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C Language for Experienced Programmers (UClOOl) is a thorough, formal introduc- 
tion to the C Programming Language. 

Internal UNIX System Calls and Libraries Using C Language (UClOll) is an intro- 
duction to UNIX application programming in C. Topics include the execution 
environment, memory management, input/output, record and file locking, pro- 
cess generation, and interprocess communication (IPC). 

UNIX System V Release 4 Device Drivers(UC1056) explores device driver mechan- 
isms, operating system supplied functions, device driver source code examples, 
installation procedures and debugging techniques. Character, STREAMS, and 
block devices are covered as well as the entire I/O subsystem. 

UNIX System V Release 4 Internals (UC1057) presents an in-depth look at UNIX 
System V, Release 4, including the process, file and I/O subsystems. New 
UNIX System V Release 4 concepts such as Network File Sharing (NFS)/ fast file 
system, and virtual file systems (VFS) are also reviewed. 

Internal System Calls and Libraries (Part 1) (UC1058) presents the C language 
programmer's interface to UNIX System V Release 4. This course covers those 
system calls and library functions not pertaining to interprocess communication. 
Interprocess communication system calls and library functions are covered in 
Part 2 of this course. 

Internal System Calls and Libraries (Part 2) (UC1059) presents UNIX System V 
Release 4 system calls and library functions pertaining to interprocess communi- 
cation. 
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Introduction 



This chapter describes the DDI/DKI, DDI-only, and DKI-only entry-point rou- 
tines a developer may include in a device driver. These are called entry-point 
routines because they provide the calling and return S5mtax from the kernel into 
the driver. For all driver tj^s, these routines are called in response to system 
calls, when the computer is started, when a device generates an interrupt, or for 
STREAMS drivers, in response to STREAMS events. 

All driver routines common to both DDI and DKI are identified with the 
(D2DK) cross reference code. All DDI-only or DKI-only routines are identified 
with the (D2D) or (D2K) reference codes respectively. 

Functions provided to allow the driver to communicate with the kemel are 
described in section 3, and use the (D3DK), (DSD), and (D3K) cross reference 
codes. 

In this section, reference pages contain the following headings: 

■ NAME describes the routine's purpose. 

■ SYNOPSIS summarizes the routine's calling and return syntax. 

■ ARGUMENTS describes each of the routine's arguments. 

■ DESCRIPTION provides general information about the routine. 

■ DEPENDENCIES lists possible dependent routine conditions. 

■ SEE ALSO gives sources for further information. 
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Each driver is organized into two parts: the base level and the interrupt level. 
The base level interacts with the kernel and the user program; the interrupt 
level interacts with the device. 

To uniquely identify a driver, a prefix string is added to the driver routine 
names. The prefix is defined in the driver's master file. For a driver with the 
pre prefix, the driver code may contain routines named pre_open, pre__close, 
pre_Lnit, pre_int, and so forth. All global variables associated with the driver 
should also use the same prefix. 

System routines can call subroutines that are assigned names by the driver 
writer. Subroutines should be declared as static, and should also use the 
driver prefix to increase code readability. 

Table 2-1 summarizes the STREAMS driver entry points described in this section. 
These entry points may be used in either DDI or DKI. 



Table 2-1: STREAMS Driver Entry Point Summary 



Routine 


Description 


put 


receive messages from the preceding queue 


srv 


service queued messages 



2-2 



DDI/DKi Reference Manual 



Overview of Driver Entry-Point Routines and Naming Conventions 



Table 2-2 sunmiarizes the block I/O driver entry points described in this sec- 
tion. These entry points may be used in either DDI or DKI, except as noted. 



Table 2-2: Driver Entry Points not Specific to STREAMS 



Kouiine 


uescnption 


iype 


chpoll 


poll entry point for a non-STREAMS char- 
acter driver 




cl.Qse 


TGHnauish access to a device 






initialize a device 


DDI only 


int 


process a device interrupt 


DDI only 


ioctl 


control a character device 




mmap 


return page frame number 


DKI only 


open 


gain access to a device 




print 


display a driver message on system console 




read 


read data from a device 




segmap 


map device memory into user space 


DKI only 


size 


return size of logical device 


DDI only 


start 


start access to a device 


DDI only 


strategy 


perform block I/O 




write 


write data to a device 
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chpoll(D2DK) 



NAME 

chpoll - poll entry point for a non-STREAMS character driver 

SYNOPSIS 

tinclude <sys/poll.h> 

chpoll (dev_t dev, short events, int anyyet, short *reventsp, 
struct pollhead **phpp) ; 

ARGUMENTS 

dev The device number for the device to be polled. 

events The events that may occur. Valid events are: 

POLLIN Data are available to be read. 

POLLOUT Data may be written without blocking. 

POLLPRI High priority data may be read. 

POLLHUP A device hangup. 

POLLERR A device error. 

anyyet A flag that is non-zero if any other file descriptors in the pollfd 
array have events pending. The poll(2) system call takes a pointer to 
an array of pollfd structures as one of its arguments. See the 
poll(2) reference page for more details. 

reventsp A pointer to a bitmask of the returned events satisfied. 

phpp A pointer to a pointer to a pollhead structure. The pollhead 
structure is defined in sys/poll.h. 

DESCRIPTION 

The chpoll entry point routine is used by non-STREAMS character device 
drivers that wish to support polling. The driver must implement the polling dis- 
cipline itself. The following rules must be followed when implementing the pol- 
ling discipline: 

1. Implement the following algorithm when the chpoll entry point is called: 

if ( event s_are_sat is fi6d__now) { 

*reventsp = inask_of_satisf ied__events; 

} else { 

*reventsp =0; 
if ( ! anyyet) 

*phpp = &my_localjpollhead_structure; 

} 

return (0) ; 

2. Allocate an instance of the pollhead structure. This instance may be tied 
to the per-minor data structure defined by the driver. The pollhead struc- 
ture should be treated as a "black box" by the driver. None of its fields 
should be referenced. However, the size of this structure is guaranteed to 
remain the same across releases. 

3. Call the pollwakeup(D3DK) function whenever an event of type events 
listed above occur. This function should only be called with one event at a 
time. 
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RETURN 

A chpoll routine should return 0 for success, or the appropriate error number. 

SEE ALSO 

pollwakeup(D3DK), poll(2) 
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NAME 

close - relinquish access to a device 

SYNOPSIS [Block and Character] 

♦include <sys/types.h> 
tinclude <sys/£ile.h> 
♦include <sys/errno.h> 
♦include <sys/open.h> 
♦include <sys/cred.h> 
♦include <sys/ddi.h> 

int p6r/iixclose(dev_t dev, int flag, int otyp, credit *credj)) ; 

ARGUMENTS 

deu Device number. 

flag File status flag, as set by the open(2) or modified by the f cntl(2) 

system calls. The flag is for information only — ^the file should always 
be closed completely. The flag is taken from the f_flag member of 
the file structure which is in file.h. Possible values are: 
FEXCL, FNDELAY, FREAD, and FWRITE. Refer to open(D2D) for 
more information. 

otyp Parameter supplied so that the driver can determine how many times 
a device was opened and for what reasons. The flags assume the 
open routine may be called many times, but the close routine 
should only be called on the last close of a device. 

OTYP__BLK close was through block interface for the device 

OTYP_CHAR close was through the raw/character interface for the 
device 

OTYP_MNT close was called as a result of a umount(2) system call; 

unmount the file system associated with the block dev- 
ice 

OTYP^SWP close a swapping device 

OTYP JLYR close a layered process (a higher-level driver called the 
close routine of the device) 

*credj> Pointer to the cred(D4D) user credential structure. 

SYNOPSIS [STREAMS] 

♦include <sys/types.h> 
♦include <sys/stream.h> 
♦include <sys/f ile . h> 
♦include <sys/errno.h> 
♦include <sys/open.h> 
♦include <$fys/cred.h> 
♦include <jsys/ddi.h> 

int pr^Jcclose(queue_t int /lag, credit *cred_p) ; 
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ARGUMENTS 

*q Pointer to queue structure used to reference the read side of the 

driver. (A queue is the central node of a collection of structures and 
routines pointed to by a queue.) 

flag File status flag. 

*cred_p Pointer to the cred(D4DK) user credential structure. 
DESCRIPTION 

For STREAMS drivers, the close routine is called by the kernel through the 
cdevsw table entry for the device. (Modules use the fmodsw table.) A non-null 
value in the d_str field of the cdevsw entry points to a streamtab structure, 
which points to a qinit structure containing a pointer to the close routine. 
Non-STREAMS close routines are called directly from the bdevsw (block) or 
cdevsw (character) tables. 

The close routine ends the connection between the user process and the device, 
and prepares the device (hardware and software) so that it is ready to be opened 
again. 

A device may be opened simultaneously by multiple processes and the open 
driver routine is called for each open, but the kernel will only call the close 
routine when the last process using the device issues a close(2) or umount(2) 
system call or exits. (An exception is a close occurring with the otyp argument set 
to OTYP_LYR, for which a close (also having otyp = OTYP^LYR) occurs for each 
open.) 

In general, a close routine should always check the validity of the minor 
number component of the dev parameter. The routine should also check permis- 
sions as necessary, by using the cred(D4D) structure (if pertinent), and the 
appropriateness of the flag and otyp parameter values. 

A close routine could perform any of the following general functions: 

disable interrupts 
hang up phone lines 
rewind a tape 

deallocate buffers from a private buffering scheme 

unlock an unsharable device (that was locked in the open routine) 

flush buffers 

notify a device of the close 

deallocate any resources allocated on open 

The close routines of STREAMS drivers and modules are called when a stream 
is dismantled or a module popped. The steps for dismantling a stream are per- 
formed in the following order. First, any multiplexor links present are unlinked 
and the lower streams are closed. Next, the following steps are performed for 
each module or driver on the stream, starting at the head and working toward 
the tail: 

1. The write queue is given a chance to drain. 
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2. The close routine is called. 

3. The module or driver is removed from the stream. 
RETURN VALUE 

The close routine should return 0 for success, or the appropriate error number. 
Refer to Appendix A for a list of DDI/DKI error numbers. Return errors rarely 
occur, but if a failure is detected, the driver should decide whether the severity of 
the problem warrants either displa5dng a message on the console or, in worst 
cases, triggering a system panic. Generally, a failure in a close routine occurs 
because a problem occurred in the associated device. 

SEE ALSO 

open(D2D), cred(D4DK) 
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NAME 

init - initialize a device 

SYNOPSIS 

void prefixinit ( ) ; 

DESCRIPTION 

init and start(D2D) routines are used to initialize drivers and the devices 
they control, init routines are executed during system initialization, and can be 
used in drivers that do not require low level system services in order to be initial- 
ized, start routines are executed after low level services are enabled, such as 
interrupts and lower level kernel interfaces, but before file systems are available. 
Most drivers can use either an init or a start routine, or they can be used in 
combination. However, an init routine must be used in any driver controlling 
a device required to bring the system up. 

Not all drivers need an init or a start routine. However, a driver must have 
either an init or start routine if it needs to allocate any data structures. 

init and start routines can perform functions such as: 

allocating buffers for private buffering schemes 

mapping a device into virtual address space 

initializing hardware (for example, system generation or resetting the 
board) 

initializing a serial device in a character driver 

Because the init and start routines are executed before there is user context, 
no functions that require user-context, such as sleep(D3DK), may be called. 

SEE ALSO 

start(D2D) 
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NAME 

int - process a device interrupt 

SYNOPSIS 

void prefixint ( int wee) ; 

ARGUMENT 

ivec Number used by the operating system to associate a driver's interrupt 
handler with an interrupting device. The makeup and interpretation of 
ivec is specific to each system implementation. In some systems, this 
number may be the logical device number, or a combination of logical 
device and logical controller numbers, used to map the correct interrupt 
routine with a subdevice. In others, this number could be the interrupt 
vector number. 

DESCRIPTION 

The int routine is the interrupt handler for both block and character hardware 
drivers. The interrupt handler is responsible for determining the reason for an 
interrupt, servicing the interrupt, and waking up any base-level driver processes 
sleeping on the interrupt completion. For example, when a disk drive has 
transfered information to the host to satisfy a read request, the disk drive's con- 
troller generates an interrupt. The CPU acknowledges the interrupt and calls the 
interrupt handler associated with that controller and disk drive. The interrupt 
routine services the interrupt and then wakes up the driver base-level process 
waiting for data. The base-level portion of the driver then conveys the data to 
the user. 

In general, most interrupt routines must do the following tasks: 
keep a record of interrupt occurrences 

return immediately if no devices controlled by a driver caused the inter- 
rupt (only for systems supporting shared interrupts) 
interpret the interrupt routine argument ivec 

reject requests for devices that are not served by the device's controller 
process interrupts that happen without cause (called spurious interrupts) 
handle all possible device errors 

wake processes that are sleeping on the resolution of an interrupt request 

There are also many tasks the int routine must perform that are driver-type and 
device specific. For example, the following types of drivers require different 
functions from their int routines: 

A block driver dequeues requests, wakes up processes sleeping on an I/O 
request, and ensures that system generation has completed. 

A terminal driver receives and sends characters. 

A printer driver ensures that characters are sent. 

In addition, the functions of an int routine are device dependent. You should 
know the exact chip set that produces the interrupt for your device. You need to 
know the exact bit patterns of the device's control and status register and how 
data is transmitted into and out of your computer. These specifics differ for 
every device you access. 
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The int routine for an intelligent controller that does not use individual inter- 
rupt vectors for each subdevice must access the completion queue to determine 
which subdevice generated the interrupt. It must also update the status informa- 
tion, set/clear flags, set/clear error indicators, and so forth to complete the han- 
dling of a job. The code should also be able to handle a spurious completion 
interrupt identified by an empty completion queue. When the routine finishes, it 
should advance the unload pointer to the next entry in the completion queue. 

If the driver called biowait(D3DK) or sleep(D3DK) to await the completion of 
an operation, the int routine must call biodone(D3DK) or wakeup(D3DK) to 
signal the process to restime. 

int is only used with hardware drivers, not software drivers. 
CAUTION: The int routine must never: 

contain calls to the sleep kernel fimction 

use functions that call sleep 

drop the interrupt priority level below the level at which the interrupt 
routine was entered 

call any ftmction or routine that requires user context (that is, if it accesses 
or alters information associated with the running process) 

NOTE: uioinove(D3DK) cannot be used in an interrupt routine when the 
uio_segflg member of the uio(D4DK) structure is set to UIOJCJSERSPACE 
(indicating a transfer between user and kernel space). 

SEEALSO 

biowait(D3DK), sleep(D3DK), biodone(D3DK), wakeup(D3DK) 
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NAME 

ioctl - control a character device 

SYNOPSIS 

♦include <sys/cred.h> 
♦include <sys/types.h> 
♦include <sys/errno.h> 

int prefixioctl (dev_t dev^ int and, int arg, int mode, credit *credj>, 
int *rvalj)) ; 

ARGUMENTS 

dev Device number. 

cmd Command argument the driver ioctl routine interprets as the opera- 
tion to be performed. It should be defined, along with an integer 
value that is actually passed, in the header file. 

The I/O control command name and value can be defined in the 
driver code itself, but this is not recommended. If I/O control com- 
mands are defined in a header file> the user program and the driver 
can both access the same definitions to ensure that they agree about 
what each I/O control command value represents. 

The I/O control command name is traditionally an all uppercase 
alphabetic string. This alphabetic name can be a mnemonic. You 
should try to keep the values for your I/O control commands distinct 
from others on the system. Each driver's I/O control commands are 
discrete, but it is possible for user-level code to access a driver with an 
I/O control command that is intended for another driver, which can 
lead to serious consequences, such as if it meant to pass "drop carrier 
on a communication line," but instead sends the argument to a disk 
where it is interpreted as "reformat drive." Permissions can be set to 
prevent most such events, but the more unique your I/O control com- 
mand values are, the safer you are. 

A number of different schemes are legal for assigning values to I/O 
control command names. The most straightforward is to use decimal 
numbers; for example 

♦define COMMANDl 01 
♦define C0MMAND2 02 

Similarly, one can assign hexadecimal numbers as values 

♦define COMMANDA OxOa 
♦define COMMANDFF Oxff 

The drawback to these methods is that one quickly gets an operating 
system that contains several instances of each I/O control command 
value, with the inherent risks discussed above. 

A common method to assign I/O control command values that are 
less apt to be duplicated is to use a left-shifted 8 scheme. For instance 
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tdefine COhMANDlO ('Q'«8|10) 
♦define COMMANDll ('Q'«8|ll) 
♦define C0MMAND12 ('Q'«8|12) 

Alternately, the shift-left-8 scheme can Be defined as a constant then 
used for the I/O control command definitions. For example 

♦define ROTA ('q'«8) 
♦define COMMAND23 (ROTAI234) 
♦define COMMAND25 (ROTA|254) 

An alternative coding style is to use enumerations for the command 
argument, which allows the compiler to do additional type checking. 

t:3^edef enum { 

XX_COMMAND10 = 'Q'«8 | 10, 

XX_C0MMAND11 = 'Q'«8 | 11, 

XX__C0MMAND12 = 'Q'«8 | 12, 
} 3tx_cnids_^t; ; 

termio(7) specifies the command types that must work for AT&T ter- 
minal drivers. Terminal drivers typically have a command to read the 
current ioctl settings and at least one other that defines new set- 
tings. 

arg Passes parameters between a user program and the driver. 

When used with terminals, the argument is the address of a user pro- 
gram structure containing driver or hardware settings. Alternatively, 
the argument may be an integer that has meaning only to the driver. 
The interpretation of the argument is driver dependent and usually 
depends on the command type; the kernel does not interpret the argu- 
ment. 

mode Contains values set when the device was opened. 

Use of this mode is optional. However, the driver may use it to deter- 
mine if the device was opened for reading or writing. The driver 
makes this determination by checking the FREAD or FWRITE setting 
(values are in file.h). 

See the flag argument description of the open routine for further 
values for the ioctl routine's mode argument. 

*cred _p Pointer to the cred(D4DK) user credential structure. 

*walj) Pointer to return yalue for calling process. The driver may elect to set 
the value which is valid only if the ioctl(D2DK) succeeds. 

DESCRIPTION 

The ioctl(D2DK) routine provides character-access drivers with an alternate 
entry point that can be used for almost any operation other than a simple transfer 
of characters in and out of buffers. Most often, ioctl is lised to control device 
hardware parameters and establish the protocol used by the driver in processing 
data. 
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The kernel looks up the device's fQe table entry, determines that this is a charac- 
ter device, and looks up the entry point routines in cdevsw. The kernel then 
packages the user request and arguments as integers and passes them to the 
driver's ioctl routine. The kemd itself does no processing of the passed com- 
mand, so it is up to the user program and the driver to agree on what the argu- 
ments mean. 

I/O control commands are used to implement the terminal settings passed from 
ttymon(lM) and stty(l), to format disk devices, to implement a trace driver for 
debugging, and to clean up character queues. Since the kernel does not interpret 
the command t5^e that defines the operation, a driver is free to define its own 
commands. 

Drivers that use an ioctl routine typically have a command to "read" the 
current ioctl settings, and at least one other that sets new settings. You can 
use the mode argument to determine if the device unit was opened for reading or 
writing, if necessary, by checking the FREAD or FWRITE setting. 

If the third argument, arg, is a pointer to user space, the driver should call the 
copyin(D3DK) and copyout(D3DK) functions to transfer data between kernel 
and user space. 

To implement I/O control comniands for a driver the following two steps are 
required: 

1. Define the I/O control command names and the associated value in the 
driver's header file and comment the commands. 

2. Code the ioctl routine in the driver that defines the functionality for 
each I/O control command name that is in the header file. 

The ioctl routine is coded with instructions on the proper action to take for 
each command. It is basically a switch statement, with each case definition 
corresponding to an ioctl name to identify the action that should be taken. 
However, the command passed to the driver by the user process is an integer 
value associated with the command name in the header file. 

It is critical that command definitions and routines be clearly commented. 
Because there is so much flexibility in how commands are used, uncommented 
commands can be very difficult to interpret at a later time. 

Terminal drivers use and support the ioctl commands defined on the ter- 
mio(7) manual page. For instance, TCGETA gets the parameters associated with 
the terminal and stores them in the structure referenced in the third argument of 
the routine call. TCSETA sets the parameters associated with the terminal from 
the structure referenced in the third argtmient. 

NOTE: STREAMS drivers do not have ioctl routines. The stream head con- 
verts I/O control commands to M_IOCTL messages, which are handled by the 
driver's put(D2DK) or srv(D2DK) routine. 

RETURN VALUE 

The ioctl routine should return 0 for success, or the appropriate error number. 
Refer to Appendix A for a list of DDI/DKI error numbers. The driver may also 
set the value returned to the calling process through the rvalj) pointer. 
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SEE ALSO 

copyin(D3DK), copyout(D3DK) 
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NAME 

xnmap - check virtual mapping for memoiy mapped device 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/cred.h> 
♦include <sys/xnman . h> 
♦include <sys/vin.h> 

int prefixrmsLp (dev_t dev, of f_t off, int prot) ; 
ARGUMENTS 

dev Device whose memoiy is to be mapped. 

off Offset within device memory at which mapping begins. 

prot Protection flag from mman.h (e.g., PROTJWRITE, PROT_READ). 
DESCRIPTION 

The mmap entry point is a required entry point for character drivers supporting 
memory-mapped devices. A memory mapped device has memory that can be 
mapped into a process's address space. The iranap(2) system call, when applied 
to a character special file, allows this device memory to be mapped into user 
space for direct access by the user application (no kernel buffering overhead is 
required). 

An iranap(D2K) routine checks if each offset is within the range of pages sup- 
ported by the device. For example, a device that has 512 bytes of memory that 
can be mapped into user space should not support offsets greater than 512. If the 
offset does not exist, then -1 is returned. If the offset does exist, ininap returns 
the masked page table entry for the page at offset off in the device's memory. 

iranap should only be supported for memory-mapped devices or pseudo-devices. 
See the segmap(D2K) reference page for further information on memory-mapped 
device drivers. 

RETURN VALUE 

If the protection and offset are valid for the device, the driver should return the 
masked page table entry, typically obtained using the function 
hat_getkpf nuro(D3K), for the page at offset off in the device's memory. If not, 
-1 should be returned. 

SEE ALSO 

seginap(D2K), hat_getkpfnum(D3K) 
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NAME 

open - gain access to a device 

SYNOPSIS [Block and Character] 

linclude Oys/types . h> 
♦include <sys/file.h> 
♦include <sys/errno.h> 
♦include <sys/open.h> 
♦include <sys/cred.h> 

prefixopen (dev_t *dev, int flag, int otyp, credit *credjj) / 

ARGUMENTS 

dev Pointer to a device number. 

Information passed from the user program open(2) or create(2) sys- 
tem call instructs the driver on how to open the file. The bit settings 
for the flag are found in file.h associated with the f_flag 
member of the file structure. Valid settings are: 

FNDELAY open the device and return immediately without sleep- 
ing (do not block the open even if there is a problem) 

FREAD open the device with read-only permission (if ORed 
with FWRITE, then allow both read and write access) 

FWRITE open a device with write-only permission (if ORed with 
FREAD, then allow both read and write access) 

otyp Parameter supplied so that the driver can determine how many times 

a device was opened and for what reasons. The flags assume the 
open routine may be called many times, but the close routine 
should only be called on the last close of a device. AH flags are 
defined in open . h. 

OTYP^BLK open occurred through block interface for the device 

OTYP_CHAR open occurred through the raw/character interface for 
the device 

OTYP_MNT the file system on the block device is being opened due 
to a mount (2) system call 

OTYP_SWP open a swapping device 

OTYP_LYR open a layered process. This flag is used when one 
driver calls another driver's open or close routine. 
In this case, there is exactly one close for each open 
called. This permits software drivers to exist above 
hardware drivers and removes any ambiguity from the 
hardware driver regarding how a device is used. This 
flag applies to both block and character devices. 

*credj) Pointer to the cred(D4DK) user credential structure. 
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SYNOPSIS [STREAMS] 

♦include <sys/file.h> 
♦include <sys/stream.h> 

prefixopen (queue_t ^cj, devjt *dev, int oflag, int sflag, credit *credjf) ; 

ARGUMENTS [STREAMS] 

*q A pointer to the read queue. (A queue is the central node of a collec- 

tion of structures and routines pointed to by a queue.) 

*dev Pointer to a device number. For modules, *dev always points to the 
device number associated with the driver at the end (tail) of the 
stream. 

oflag Valid oflag values are the same as those listed above, with the excep- 
tion that FAPPEND, FCREAT, and FTRUNC have no meaning to a 
STREAMS device. For modules, o/Iog is always set to 0. 

sflag Valid values are as follows: 

CLONEOPEN Eliminates the need for user processes to poll many 
minor devices when looking for an imused one. If the 
driver wishes to assign the device a device file, the 
open routine must assign and return a minor number. 
If no device file is required, the open routine does not 
have to return a minor number. 

MODOPEN Indicates that an open routine is being called for a 
module, not a driver. Drivers should return error 
nimibers or 0 if an open is attempted with sflag set to 
MODOPEN. 

0 Indicates a driver opened directly, without calling the 

clone driver. 

*credj) Pointer to the cred(D4DK) user credential structure. 
DESCRIPTION 

The driver's open routine is called by the kernel through the cdevsw or 
bdevsw entry for the device during an open(2) or a inount(2) on the special file 
for the device. The routine should verify that the minor number component of 
dev is valid, that the type of access requested by otyp and flag is appropriate for 
the device, and, if required, check permissions using the user credentials pointed 
to by credj). 

RETURN VALUE 

The open routine should return 0 for success, or the appropriate error number. 
Refer to Appendix A for a list of DDI/DKI error numbers. 

SEE ALSO 

close(D2DK) 
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NAME 

print - display a driver message on system console 

SYNOPSIS 

♦include <sys /types .h> 
♦include <sys/errno.h> 

int prefixprint (dev_t dev, char *str) ; 

ARGUMENTS 

dev Device number. 

*str Pointer to a character string describing the problem. An explanation 

of the problem contained in the string should be included in the driver 
output* 

DESCRIPTION 

The print routine is called indirectly by the kernel through the bdevsw entry 
for the device when the kernel has detected an exceptional condition (such as out 
of space) in the device, to display the message on the console, the driver should 
use the cinn_err(D3DK) kernel function. 

RETURN VALUE 

The print routine should return 0 for success, or the appropriate error number. 
Refer to Appendix A for a list of DDI/DW error numbers. The print routine 
can fail if the driver implemented a non-standard print routine that attempted 
to perform error logging, but was unable to complete the logging for whatever 
reason. Generally, since most print routines call the cinn_err(D3DK) function, 
and this function is declared as void, return values are seldom returned from 
this routine. If a failure occurs, call cmn^err to display a message to the opera- 
tor. 

SEE ALSO 

cm err(D3DK) 
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NAME 

put - receive messages from the preceding queue 

SYNOPSIS 

♦include <sys/types.h> 
tinclude <sy8/streain.h> 
♦include <sys/stropts.h> 

void pr^/zxrput (queue_t inblk_t mp) ; /* read side */ 
void prg/ijcwput (queue_t inblk_t mp) ; /* write side */ 

ARGUMENTS 

*q Pointer to the queue(D4DK) structure. 

mp Pointer to the message block. 

DESCRIPTION 

The primary task of the put routine is to coordinate the passing of messages 
from one queue to the next in a stream. The put routine is called by the preced- 
ing stream component (module, driver, or stream head), put routines are desig- 
nated "write" or "read" depending on the direction of message flow. 

With few exceptions, a module or driver must have a put routine. One excep- 
tion is the read side of a driver, which does not need a put routine because there 
is no component downstream to call it. The put routine is always called before 
the component's corresponding srv(D2DK) (service) routine, and so put should 
be used for the immediate processing of messages. 

A put routine must do at least one of the following when it receives a message: 

pass the message to the next component on the stream by calling the 
putnext(D3DK) function 

process the message, if immediate processing is required (for example, 
high priority messages) 

enqueue the message (with the putq(D3Dk) function) for deferred pro- 
cessing by the service srv(D2DK) routine 

Typically, a put routine will switch on message type, which is contained in the 
db^type member of the datab structure pointed to by mp. The action taken by 
the put routine depends on the message type. For example, a put routine 
might process high priority messages, enqueue normal messages, and handle an 
unrecognized message by changing its type to M_IOCNAK (negative acknowledge- 
ment) and sending it back to the stream head using the qreply(D3DK) function. 

The putq(D3DK) function can be used as a module's put routine when no spe- 
cial processing is required and all messages are to be enqueued for the srv rou- 
tine. 

put routines do not have user context and so may not call sleep(D3DK). 
SEE ALSO 

The BCI Driver Development Guide, Chapter 7, "STREAMS" 
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The STREAMS Programmer's Guide 

streamtab(D4DK), putctl(D3DK), putctll(D3DK), putnext(D3DK), 
putq(D3DK), qreply(D3DK), srv(D2DK) 
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NAME 

read - read data from a device 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/errno.h> 
♦include <sys/open.h> 
♦include <sys/uio.h> 
♦include <sys/cred.h> 

prefixread (dev_t deu, uio *uioj), credit *cred_p) ; 

ARGUMENTS 

dev 

Device number. 

*uio_p Pointer to the uio(D4DK) structure that describes where the data is to 
be stored in user space. 

*credj) Pointer to the cred(D4DK) user credential structure for the I/O tran- 
saction. 

DESCRIPTION 

The driver read routine is called indirectly through cdevsw by the read(2) 
system call. The read routine should check the validity of the minor nimiber 
component of dev and the user credentials contained in the cred(D4DK) struc- 
ture pointed to by *cred_p (if pertinent). The read routine should supervise the 
data transfer into the user space described by the uio(D4DK) structure. 

RETURN VALUE 

The read routine should return 0 for success, or the appropriate error number. 
Refer to Appendix A for a list of error values. 

SEE ALSO 

write(D2DK) 
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NAME 

segmap - map device memory into user space 

SYNOPSIS 

♦include <sys/types . h> 
# include <sys/xninan.h> 
♦include <sys/param.h> 
♦include <sys/vm.h> 

int pr^xaegoiap (dev_t dev, of f_t o^,struct as *asp, addr_t *addrp, 
of f_t len, unsigned int prot, unsigned int maxprot, 
unsigned int ^ags, credit *credjf); 

ARGUMENTS 

dev Device whose memory is to be mapped. 

off Offset within device memory at which mapping begins. 

*a$p Pointer to the address space into which the device memory should be 
mapped. 

*addrp Pointer to the address in the address space to which the device 
memory should be mapped. 

len Length (in bytes) of the memory to be mapped. 

prot Protection flag (from sys/mman.h) for example, PROT^WRITE^ 

PROT_READr PROT_USER (indicating the mapping is being done as a 
result of a inmap(2) system call). 

maxprot Maximum protection flag possible for attempted map (PROT_WRITE 
may be masked out if the user opened the special file read-only). If 
(maxprot & prot) != prot then there is an access violation. 

flags Flags indicating type of mmap (for example, MAP_SHARED vs. 

MAP_PRIVATE), whether the user specified an address (MAP_FIXED). 
Found in sys/mman.h. 

*credj> Pointer to the cred(D4DK) user credentials structure. 

DESCRIPTION 

The segmap entry point is an optional routine for character drivers that support 
memory mapping. The mmap(2) system call, when applied to a character special 
file, allows device memory to be mapped into user space for direct access by the 
user application (no kernel buffering overhead is required). 

Typically, a character driver that needs to support the mmap(2) system call sup- 
plies either a single mmap(D2K) entry point, or both an mmap and a segmap 
entry point routine (see the mmap(D2K) reference page). If no segmap entry 
point is provided for the driver, the default kernel segmap routine is called to 
perform the mapping. 

A driver for a memory-mapped device would provide a segmap entry point if it: 

requires the mapping to be done through a virtual memory (VM) segment 
driver other than the default seg_dev driver provided by the kernel 
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needs to control the selection of the user address at which the mapping 
occurs in the case where the user did not specify an address in the 
inmap(2) system call 

Among the responsibilities of a segmap entry point are: 

Select a segment driver and check the memory map flags for appropriate- 
ness to the segment driver. For example, the seg_dev segment driver 
does not support memory maps that are marked MAP_PRIVATE (copy- 
on-write). 

Verify that the range to be mapped makes sense in the context of the dev- 
ice (does the offset and length make sense for the device memory that is 
to be mapped). Typically, this task is performed by calling the 
inmap(D2K) entry point. 

If MAP_FIXED is not set in flags, obtain a user address at which to map. 
Otherwise, immap any existing mappings at the user address specified. 

Perform the mapping and return the error status if it fails. 

RETURN VALUE 

The routine returns 0 if the driver is successful in performing the memory map 
of its device address space into the specified address space. An error number 
should be returned on failure. For example, valid error numbers would be 
ENXIO if the offset/length pair specified exceeds the limits of the device memory, 
or EINVAL if the driver detects an invalid t5^e of mapping attempted. 

SEE ALSO 

inmap(D2K) 
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NAME 

size - return size of logical device 

SYNOPSIS 

♦include <sys/types.h> 

prefixaize (dev_t dev) ; 

ARGUMENT 

dev The logical device number. 

DESCRIPTION 

Returns the number of 512-byte units on a logical device (partition). Although 
this routine is not required, it is recommended that new drivers include one as 
the Release 4.0 kernel calls the size routine on behalf of certain UNIX com- 
mands such as stat(3G). 

RETURN VALUE 

The number of 512 byte imits on the logical device specified by dev, or -1 on 
failure. 
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NAME 

srv - service queued messages 

SYNOPSIS 

♦include <sys/types.h> 
finclude <sys/stream.h> 
♦include <sys/stropts . h> 

void pr^Jcrsrv(queue_t ^) ; /* read side */ 
void pr^Ji:wsrv(queue_t <f) ; /* write side */ 

ARGUMENTS 

*q Pointer to the queue(D4DK) structure 

DESCRIPTION 

The optional service (srv) routine may be included in a STREAMS module or 
driver for one or more of the following reasons: 

to provide greater control over the flow of messages in a stream 

to make it possible to defer the processing of some messages to avoid 
depleting system resources 

to combine small messages into larger ones, or break large messages into 
smaller ones 

to recover from resource allocation failure. A module's or driver's 
put(D3DK) routine can test for the availability of a resource, and if it is 
not available, enqueue the message for later processing by the srv rou- 
tine. 

A message is first passed to a module's or driver's put(D2DK) routine, which 
may or may not do some processing. It must then either 

pass the message to the next stream component with putnext(D3DK) 

if a srv routine has been included, it may call the putq(D3DK) function 
to place the message on the queue 

Once a message has been enqueued, the STREAMS scheduler controls the calling 
of the service routine. Service routines are called in FIFO order by the scheduler. 
No guarantees can be made about how long it will take for a srv routine to be 
called except that it will happen before any user level process are run. 

Every stream component (stream head, module or driver) has limit values it uses 
to implement flow control. Tunable high and low water marks are checked to 
stop and restart the flow of message processing. Flow control limits apply only 
between two adjacent components with srv routines. 

STREAMS messages can be defined to have up to 256 different priorities to sup- 
port some networking protocol requirements for multiple bands of data flow. At 
a minimimi, a stream must distinguish between normal (priority zero) messages 
and high priority messages (such as M_IOCACK). High priority messages are 
always placed at the head of the srv routine's queue, after any other enqueued 
high priority messages. Next are messages from all included priority bands. 
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which are enqueued in decreasing order of priority. Each priority band has its 
own flow control limits. If a flow controlled band is stopped, all lower priority 
bands are also stopped. 

Once a srv routine is called by the STREAMS scheduler it must process all mes- 
sages on its queue. The following steps are general guidelines for processing 
messages. Keep in mind that many of the details of how a srv routine should 
be written depend of the implementation, the direction of flow (upstream or 
downstream), and whether it is for a module or a driver. 

L Use the getq(D3DK) function to get the next enqueued message. 

2. If the message is high priority, process (if appropriate) and pass to the next 
stream component with the putnext(D3DK) function. 

3. If it is not a high priority message (and therefore subject to flow control), 
attempt to send it to the next stream component with a srv routine. Use 
bcanput(D3DK) to determine if this can be done. 

4. If the message cannot be passed, put it back on the queue with 
putbq(D3DK). If it can be passed, process (if appropriate) and pass with 
putnext. 

NOTE: Each stream module has a read and write service (srv) routine. If a ser- 
vice routine is not needed (because the put routine processes all messages), a 
NULL pointer should be placed in module's qinit structure. Do not use the 
nulldev routine instead of the NULL pointer. Use of nulldev for a srv rou- 
tine may result in flow control errors. 

SEE ALSO 

Tl[ie BCI Driver Devebpmmt Guiik/ChsLpter 7,/'STl^ 

The STREAMS Programmer's Guide, Chapter 5, "Messages'' 

bcanput(D3DK), canput(D3DK), getq(D3DK), put(D2DK), putbq(D3DK), 
putnext(D3DK), putq(D3DK), queue(D4DK) 
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NAME 

start - start access to a device 

SYNOPSIS 

void preftxatart () ; 

DESCRIPTION 

The start routine is called when a computer starts placing a device into a 
known state. At the time this routine is called, the developer cannot depend on 
root being moimted. However, the developer can depend on low level system 
services being available such as interrupts enabled. 

A start routine may perform the following types of activities: 

initialize data structures for device access 

allocate buffers for private buffering scheme 

map device into virtual address space 

initialize hardware (for example, perform a system generation and reset 
the board) 

initialize the serial device for character drivers 
initialize any static data associated with the driver 

SEE ALSO 

init(D2DK) 
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NAME 

strategy - perform block I/O 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/buf .h> 

int pr^xstrategy (struct buf *bp) ; 
ARGUMENT 

bp Pointer to the buf (D4DK) structure. 

DESCRIPTION 

The strategy routine is called indirectly (through bdevsw) by the kernel to 
read and write blocks of data on the block device, strategy may also be called 
directly or indirectly (via a call to the kernel function physiock(D3D)), to sup- 
port the raw character interface of a block device (read(D2DK), write(D2DK) 
and ioctl(D2DK)). The strategy routine's responsibility is to set up and ini- 
tiate the transfer. 

RETURN VALUE 

On an error condition, OR the b_f lags member of the buf (D4DK) structure 
with B_ERROR and set the b_error member to the appropriate error value. 

SEE ALSO 

read(D2DK), write(D2DK) 
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NAME 

write - write data to a device 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/errno.h> 
♦include <sys/open.h> 
♦include <sys/cred.h> 

int prefixvir ite (dev_t dev, uio_t *uioj), credit *cred_p) ; 

ARGUMENTS 

dev 

Device number. 

uio_p Pointer to the uio(D4DK) structure that describes where the data is to 
be stored in user space. 

credj) Pointer to the cred(D4DK) user credential structure for the I/O tran- 
saction. 

DESCRIPTiON 

Used for character or raw data I/O, the driver write routine is called indirectly 
through cdevsw by the write(2) system call. The write routine supervises the 
data transfer from user space to a device described by the uio(D4DK) structure. 

The write routine should check the validity of the minor number component of 
dev and the user credentials pointed to by credjp (if pertinent), 

RETURN VALUE 

The write routine should return 0 for success, or the appropriate error number. 
Refer to Appendix A for a list of DDI/DKI error numbers. 

SEE ALSO 

read(D2DK) 
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Introduction 



This chapter describes the kernel functions available for use by device drivers. 
Each function is described in a separate entry. Most functions are part of both 
DDI and DKI-^-these are indicated by the (D3DK) cross reference code. Func- 
tions belonging only to DDI are cross-referenced by (DSD) and DKI-only func- 
tions are marked (D3K). 

In this section, the information for each driver function is organized under the 
following headings: 

■ NAME summarizes the function's purpose. 

■ SYNOPSIS shows the syntax of the function's entry point in the source 
code. #include statelnents are shown for required header files. 

■ ARGUMENTS describes any arguments required to invoke the function. 

■ DESCRIPTION describes general information about the function. 

■ RETURN VALUE describes the return values and messages that can result 
from invoking the function. 

■ LEVEL indicates from which driver level (base or interrupt) the function 
can be called. 

■ SEE ALSO indicates functions that are related by usage and sources, and 
which can be referred to for further information. 

■ EXAMPLE shows how the function can be used in driver code. 



Ipll] The ddi.h header file undefines macros that have been reimplemented as 
liSpTE functions in UNIX System V Release 4.0. Always place ddi.h at the end of 
the list of include statements to avoid contention between macro and func- 
[ tion declarations. 
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Function Summary 

Table 3-1 summarizes the STREAMS functions described in this section. 
STREAMS functions may be used in either DDI or DKI. 



Table 3-1 : STREAMS Kernel Function Summary 



Routine 


Descriotion 


adjxnsg 


remove the specified number of bytes from 
a message 


allocb 


allocate a message block 


backq 


get pointer to the previous queue 




fpst foT" flow rnntrol in snprifipd orioiitv 
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band 


bufcall 


get buffer when allocb fails 




LsJl IKJkJLLi. ill d ilLcadCl^C ULlcLlC 










datamsg 


test whether a message is a data message 


dupb 


duplicate a message block descriptor 


dupmsg 


duplicate a message 


enableok 


enable a queue for service 


esballoc 


allocate a message block with a shared 
buffer 


esbbcall 


get message header when esballoc fails 


flushband 


flush messages for specified priority band 


flushq 


remove messages from a queue 


f reeb 


free a message block 


f reemsg 


free all message blocks in a message 


getq 


get a message from the front of a queue 


insq 


insert sl message into a queue 


linkb 


concatenate two message blocks 
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Table 3-1: STREAMS Kernel Function Summary (continued) 



Routine 


Description 


msgdsize 


return the number of bytes in a message 


noenable 


prevent a queue from being scheduled 


OTHERQ 


get a pointer to a module's other queue 


pullupmsg 


concatenate bytes in a message 


putbq 


place a message at the head of a queue 


putctl 


put a control message on a queue 


putctll 


put a control message with a one-byte 
parameter on a queue 


putnext 


send a message to the next module in the 
stream 


putq 


put a message on a queue 


qenable 


enable a queue 


qreply 


send a message in the reverse direction 


qsize 


find the number of messages on a queue 


RD 


get a pointer to a module's read queue 


rmvb 


remove a message block from a queue 




remove a message from a queue 


SAMESTR 


test if next queue is same type 


strlog 


submit messages for logging 


strqget 


get information about a queue 


strqset 


change information about a queue 


testb 


check for an available buffer 


unlinkb 


remove the message block from the head of 

a message 


WR 


get pointer to this module's write queue 
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Table 3-2 summarizes the functions not specific to STREAMS. Functions can be 
used in either DDI or DKI, except as noted. 



Table 3-2: Kernel Functions Not Specific to STREAMS 



Routine 


Description 


Type 


bcopy 


copy data between locations in the kernel, 
for example, from one buffer to another 




biodone 


release buffer after block I/O and wakeup 




biowait 


suspend processes pending completion of 
block I/O 




bp inapi.n 


allocate virtual address space 




bp_inapout 


deallocate virtual address space 




brelse 


return buffer to the kernel 




btop 


return number of memory pages contained 
in specified number of bytes (downward 
rounding) 




btopr 


return number of memory pages contained 
in specified number of bytes (upward 
rounding) 




bzero 


clear memory for a number of bytes 




clrbuf 


erase buffer contents 




cmnjerr 


display message or panic the system 




copyin 


copy data from user space to the driver 




copyout 


copy data from the driver to user space 




delay 


delay for specified number of clock ticks 




cbnajpageio 


break up DMA requests 


DDI only 


drvjgetpam 


retrieve kernel state information 




drvjiztousec 


convert from clock ticks to microseconds 




drv_priv 


determine driver privileges 




drvjusectohz 


convert from microseconds to clock ticks 
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Table 3-2: Kernel Functions Not Specific to STREAMS (continued) 



RftlltlTIP 




Tvr>G 


drvjisecwait 


wait for specified number of microseconds 




etoimajor 


convert external major number to internal 
major number 


DDI only 


freerbuf 


free a raw buffer header 




getemajor 


get external major number 


DDI only 


geteminor 


get external minor number 


DDI only 


geterror 


return an I/O error 




getxnajor 


get major number 




getminor 


get minor number 




getrbuf 


get a raw buffer header 




getvec 


get an interrupt vector for a given virtual 
board address 


DDI only 


hatjgetkpfnum 


get page frame number for address 


DKIonly 


hdeeqd 


initialize error logging in the hard disk 


DDI only 


hdelog 


log a hard disk error 


DDI only 


itoemajor 


convert internal major number to external 
nimiber 


DDI only 


kroemjalloc 


allocate storage from kernel free space 






iree previously aiiocatea Kernel memory 




kxnem_zalloc 


allocate and clear storage from kernel free 
memory 




kvtophys 


convert kernel virtual to physical address 


DDI only 


itakedevice 


create a device number 




xnax 


return the larger of two integers 




xnin 


return the smaller of two integers 




pagej:iumtopp 


convert page frame number to page struc- 
ture 
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Table 3-2: Kernel Functions Not Specific to STREAMS (cx)ntinued) 



Routine 


Description 


Type 


page ppuonuin 


Luiivcn page 0iruv,Tu.rc xu page iraiiic 

number 




physiock 


validate and issue raw I/O request 


DDI only 


X X wci JVC 


inform a nrr>fPCft tlisii" an pvpnf Iiag nrr'iiTTpH 
ixuv^iiii a pi\./vco9 Liiai an cvcxii iiao vyvvuxxcvt. 




ptob 


convert size in pages to size in bytes 




rmalloc 


allocate space from a private space manage- 
ment map 




intif re€ 


free space back into a private space 
management map 




rminit 


initialize a private space management map 




XlllOd^WCUiU 


ixic xxiap & waxt xiaK iv-ix waJN.cu.p 




ntiwant 


wait for free memory 




Sl66p 


suspend execution 




spl 


suspend or allow interrupts 




timeout 


call function in clock ticks 




uioxnove 


copy kernel data using uio structure 




untimeout 


cancel timeout with matching ID 




ureadc 


add character to uio structure 




useracc 


verify user access to data structures 




uwritec 


remove a character from a uio structure 




vtop 


convert virtual to physical address 


DDI only 


wakevip 


resume suspended execution 
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NAME 



ad jmsg - trim bytes from a message 



SYNOPSIS 



♦include <sys/3tream.h> 

int ad jmsg (itiblk_t *mp, int len) ; 



ARGUMENTS 

*tnp 

len 



Pointer to the message to be trimmed. 
The number of bytes to be removed. 



DESCRIPTION 

ad jmsg removes bytes from a message. | len \ (the absolute value of len) specifies 
how many bytes are to be removed. If len is greater than 0, bytes are removed 
from the head of the message. If len is less than 0, bytes are removed from the 
tail, ad jmsg fails if \len\ is greater than the number of bytes in mp. 

RETURN VALUE 

If the message can be trimmed successfully, 1 is returned. Otherwise, 0 is 
returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
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MAME 

allocb - allocate a message block 

SYNOPSIS 

♦include <sys/stream.h> 

iriblk_t *allocb (int size, int pri) ; 
ARGUMENTS 

size The number of bytes in the message block. 

pri Priority of the request (no longer used). 

DESCRIPTION 

allocb tries to allocate a STREAMS message block. Buffer allocation fails only 
when the system is out of memory. If no buffer is available, the 
buf call(D3DK) function can help a module recover from an allocation failure. 

NOTE: The pri argument is no longer used in UNIX System V Release 4, but is 
retained for compatibility with existing drivers. 

The following figure identifies the data structure members that are affected when 
a message block is allocated. 



b_c6nt (0) 
b_rptr — 
b_wptr — 
b_datap — 



message block data block data buffer 

(Jriblk_t) (dblk_t) 

RETURN VALUE 

If successful, allocb returns a pointer to the allocated message block of type 
M^DATA (defined in 3ys/stream.h). If a block cannot be allocated, a NULL 
pointer is returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
STREAMS Programmer's Guide, Chapter 5, "Messages" 
bufcall(D3DK), esballoc(D3DK), esbbcall(D3DK), testb(D3DK) 
EXAMPLE 

Given a pointer to a queue (q) and an error number {err), the sendee rr or rou- 
tine sends an M_ERROR type message to thie stream head. 

If a message cannot be allocated, 0 is returned, indicating an allocation failure 
(line 8). Otherwise, the message type is set to MJERROR (line 10). Line 11 incre- 
ments the write pointer (bp->b_wptr) by the size (one byte) of the data in the 
message. 



db_base ' 
db__lim 

db_type (M_DATA) 
db_class (6) 
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A message must be sent up the read side of the stream to arrive at the stream 
head. To determine whether q points to a read queue or a write queue, the q- 
>CLf lag member is tested to see if QREADR is set (line 13). If it is not set, q 
points to a write queue, and in line 14 the Rp(D3DK) function is used to find the 
corresponding read queue. In line 15, the putnext(D3DK) function is used to 
send the message upstream, returning 1 if successful. 

1 send^error (q, err) 

2 queue_t *q; 

3 unsigned char err; 



4 { 

5 

6 



inblk__t *bp; 



7 



if ((bp - allocb(l, BPRI_HI) ) 
return (0); 



NULL) /* allocate msg. block */ 



8 



9 
10 



bp->b_datap->db_type - M__ERROR; 
*bp->b__wptr++ P! err; 



/* set msg type to M_ERROR */ 
/* increment write pointer */ 



11 



12 



14 



13 



15 
16 

17 } 



putnext (q,bp) ; 
return (1) ; 



if (!qT->q_flag & QREADR)) 
q - RD(q); 



/* if not read queue */ 
/* get read queue */ 
/* send message upstream */ 
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NAME 

backq - get pointer to the queue behind the current queue 

SYNOPSIS 

♦include <sys/stream.h> 

queue_t *backq (queue_t *c^) ; 
ARGUMENT 

-cq The pointer to the current queue. queue_t is an alias for the 

queue(D4DK) structure. 

DESCRIPTION 

backq returns a pointer to the queue preceding cq (the current queue). If cq is a 
read queue, backq returns a pointer to the queue downstream from cq, unless it 
is the stream end. If cq is a write queue, backq returns a pointer to the next 
queue upstream from cq, unless it is the stream head. 

RETURN VALUE 

If successful, backq returns a pointer to the queue preceding the current queue. 
Otherwise, it returns NULL. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS'' 
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NAME 

bcanput - test for flow control in specified priority band 

SYNOPSIS 

♦include <sys/stream.h> 

int bcanput (queue__t unsigned char pri) ; 

ARGUMENT 

q Pointer to the message queue. 

pri Message priority. 

DESCRIPTION 

Like the canput(D3DK) function, bcanput searches through the stream (start- 
ing at q) until it finds a queue containing a service routine where the message can 
be enqueued, or until it reaches the end of the stream. If found, the queue con- 
taining the service routine is tested to see if there is room for a message in the 
queue. If the queue is full, bcanput sets the QWANTW flag to back-enable the 
caller's service routine. 

If pri is 0, the bcanput call is equivalent to a call to canput. 

NOTE: You are responsible for both testing a queue with bcanput and refrain- 
ing from placing a message on the queue if bcanput fails. 

RETURN VALUE 

A 1 is returned if a message of priority pri can be placed on the queue, or if the 
band does not yet exist on the queue. A 0 is returned if the priority band is 
flow-controlled. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
canput(D3DK), putbq(D3DK), putnext(D3DK) 
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NAME 

bcopy - copy data between address locations in the kernel 

SYNOPSIS 

♦include <sys/types .h> 

int bcopy (caddr_t from, caddr_t to, long bcount) ; 
ARGUMENTS 

from Source address from which the copy is made. 
to Destination address to which copy is made. 

bcount The number of bytes moved. 
DESCRIPTION 

bcopy copies bcount bytes from one kernel address to another. If the input and 
output addresses overlap, the command executes, but the results may not be as 
expected. 

CAUTION: The from and to addresses must be within the kernel space. No range 
checking is done. If an address outside of the kernel space is selected, the driver 
may corrupt the system in an unpredictable way. 

Note that bcopy should never be used to move data in or out of a user buffer, 
because it has no provision for handling page faults. The user address space can 
be swapped out at any time, and bcopy always assumes that there will be no 
paging faults. If bcopy attempts to access the user buffer when it is swapped 
out, the system will panic. It is safe to use bcopy to move data within kernel 
space, since kernel space is never swapped out. 

RETURN VALUE 

Under all conditions, 0 is returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 6, "Input/Output Operations" 
copyin(D3DK), copyout(D3DK) 
EXAMPLE 

An I/O request is made for data stored in a RAM disk. If the I/O operation is a 
read request, the data is copied from the RAM disk to a buffer (line 7). If it is a 
write request, the data is copied from a buffer to the RAM disk (line 11). The 
bcopy function is used since both the RAM disk and the buffer are part of the 
kernel address space. 

1 #def ine RAMDNBLK 1000 /* blocks in the RAM dlsJc */ 

2 #define RAMDBSIZ 512 /* bytes per block */ 

3 char ramdblks [RAMDNBLK] (RAMDBSIZ] ; /* blocks forming RAM disk */ 

4 

5 if (bp->b__f lags & B__READ) /* if read request, copy data from RAM */ 

6 /* disk data block to system buffer */ 

7 bcopy (&ramdblks [bp->b_blkno] [0] , bp->b_un.b_addr, bp->b_bcount) ; 
8 
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9 else /* else write request, copy data from a */ 

10 /* system buffer to RAM disk data block */ 

11 bcopy(bp->b_un.b_addr, firamdblks Ibp->bj5lkno] [0] , bp->b_bcount ) ; 
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NAME 

biodone - release buffer after block I/O and wakeup processes 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/buf .h> 

void biodone (struct buf *bp) ; 
ARGUMENT 

*bp Pointer to the buffer header structure defined in buf .h. This is the 

address of the buffer header associated with the buffer where the I/O 
occurred. 

DESCRIPTION 

The biodone function is called by either the driver int(D2D) or 
strategy(D2DK) routines when a block I/O request is complete. In general, 
biodone awakens sleeping processes waiting for the I/O to complete, sets the 
B_DONE flag in the buf structure b_f lags field, and releases the block if the 
I/O is asynchronous. 

For drivers that wish to make multiple I/O requests without releasing and reallo- 
cating a buffer header for each individual request, biodone provides the capa- 
bility to check for an additional function to be called before the buffer header is 
released. Additional routines to be called from biodone are referenced by the 
(*b_biodone) field of the buf structure. 

biodone performs the following functions in the order presented: 

checks the (*biodone) field of the buf structure for additional routines 
to be called. If an additional routine is referenced, it is called and the 
functions listed below are not completed. 

awakens the process(es) that called sleep(D3DK) to wait for the buffer 
header if I/O is synchronous 

releases the block if I/O is asynchronous and awakens processes awaiting 
asynchronous I/O 

marks b_f lags of buffer with B_DONE 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 9, "Synchronizing Hardware and Software 
Events" 

biowait(D3DK), buf (D4DK), delay(D3DK), int(D3D), strategy(D3DK), 
sleep(D3DK), timeout (D3DK), untimeout(D3DK), wakeup(D3DK) 

EXAMPLE 

Generally, the first validation test performed by any block device 
strategy(D2DK) routine is a check for an end-of-file (EOF) condition. The 
strategy routine is responsible for determining an EOF condition when the 
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device is accessed directly. If a read request is made for one block beyond the 
limits of the device (line 10), it will report an EOF condition. Otherwise, if the 
request is outside the limits of the device, the routine will report an error condi- 
tion. In either case, report the I/O operation as complete (line 27). 



1 #def ine RAMDNBLK 1000 /* Number of blocks in RAM disk */ 

2 fdefine RAMDBSIZ 512 /* Number of bytes per block */ 

3 char rarodb Iks [RAMDNBLK] [RAMDBSIZ] ; I* Array containing RAM disk */ 
4 

5 ramdstrategy (bp) 

6 register struct buf *bp; 

7 { 

8 register daddr_t blkno - bp->b_blkno; /* get block number */ 
9 

10 if (blkno < 0 I I blkno >- RAMDNBLK) { 

11 /* 

12 * If requested block is outside RAM disk 

13 * limits, test for EOF which could result 

14 * from a direct (physiock) request. 

15 */ 

16 if (blkno — RAMDNBLK && bp->b_flags & B_READ) { 

17 /* 

18 ♦ If read is for block beyond RAM disk 

19 * limits, mark EOF condition. 

20 */ 

21 bp->b_resid — bp->b_bcount; /* compute return value */ 
22 

23 } else ( /* I/O attempt is beyond */ 

24 bp->b_error - ENXIO; /* limits of RAM disk */ 

25 bp->b_flags |- B_ERROR; /* return error */ 

26 } /* endif */ 

27 biodone(bp); /* mark I/O complete (B_DONE) */ 

28 /* 

29 * Wake any processes awaiting this I/O 

30 * or release buffer for asynchronous 

31 * (B_ASYNC) request. 

32 */ 

33 return; 

34 } /* endif */ 
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NAME 

biowait - suspend processes pending completion of block I/O 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/buf .h> 

int biowait (struct buf *bp) ; 

ARGUMENT 

*bp Pointer to the buf structure. 

DESCRIPTION 

The biowait function suspends process execution during a block I/O transfer 
by calling sleep(D3DK). Block driver routines using the buf structure to allo- 
cate buffers can use the biowait function to suspend a process while waiting 
for a read or write request to complete. 

The biowait function is one of three functions used to aid block I/O transfers. 
The other functions in this group are biodone(D3DK), which notifies biowait 
that the I/O is complete, and brelse, which frees the buffer allocated for the 
transfer. 

Drivers using the biowait function must also include the biodone(D3DK) 
function in their interrupt routines. The biodone ftmction awakens biowait 
when the I/O transfer is complete. 

Because biowait calls sleep, biowait cannot be called from an interrupt 
routine or from an init(D2D) routine. 

RETURN VALUE 

None. However, biowait returns any error that may have occured during the 
I/O transfer to the user using geterrpr(D3DK). 

LEVEL 

Base Only (Do not call from an interrupt routine) 
SEE ALSO 

biodone(D3DK), brelse(D3DK), sleep(D3DK), timeout (D3DK), 
untiineout(D3DK), wakeup(D3DK) 
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NAME 

bp_xnapin - allocate virtual address space 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/buf .h> 

vaddr_t bp_xnapin (struct buf *bp) ; 

ARGUMENTS 

*bp Pointer to the buffer header structure. 

DESCRIPTION 

The bpjnaapin function is used to map virtual address space to a page list main- 
taned by the buffer header during a paged -I/O request. bp_mapin allocates sys- 
tem virtual address space, maps that space to the page list, and returns the offset 
into the map. The offset is stored in the bp->b_un.b_addr field of the of the 
buf structure (see buf (D4DK)). Virtual address space is then deallocated using 
the bpjmapout function. 

If a NOLL page list is encountered, bp_jnapin returns without allocating space 
and no mapping is performed. 

RETURN VALUE 

The starting address of the allocated system virtual address space. 

LEVEL 

Base 

SEE ALSO 

bp_niapout(D3DK), buf(D4DK) 
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NAME 

bpjnaapout - deallocate virtual address space 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/buf.h> 

void bp__xnapin (struct buf *hp) ; 

ARGUMENTS 

bp Pointer to the buffer header structure. 

DESCRIPTION 

This function deallocates system virtual address space allocated by a previous call 
to bp_jivapin(D3DK). bp_inapin maps virtual address space to a page list 
maintained by the buffer header for a paged-I/O request, then returns the offset 
into the map to the b__addr field of the buf structure. 

RETURN VALUE 

None 

LEVEL 

Base 

SEE ALSO 

bp_mapin(D3DK), buf(D4DK) 
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NAME 

brelse - return biiffer to the bf reelist 

SYNOPSIS 

♦include <sys /types .h> 
♦include <sys/buf .h> 

void brelse (struct buf *bp) / 

ARGUMENT 

*bp Pointer to the buf structure. 

DESCRIPTION 

The brelse function returns a previously allocated buffer to the buffer free list. 
First, brelse wakes up processes sleeping on the buffer. After the driver func- 
tion is finished with the buffer, brelse returns the buffer header to a list of free 
buffers and awakens any processes that called sleep(D3DK) to wait for a free 
buffer on the bf reelist. 

RETURN VALUE 

None, however, if b__f lags has B_ERROR enabled due to an error in an earlier 
I/O transfer, b__f lags is ORed with B__STALE and B_AGE, B_ERROR and 
B__DELWRI are disabled, and b_error is set to 0. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 6, "Input/Output Operations" 
clrbuf(D3DK), biodone(D3DK), biowait(D3DK) 
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NAME 

btop - convert size in bytes to size in pages (round down) 

SYNOPSIS 

♦include <sys/ddi.h> 

unsigned long btop (unsigned long numbytes) ; 

ARGUMENT 

numbytes Number of bytes. 

DESCRIPTION 

The btop function returns the number of memory pages that are contained in 
the specified number of bytes, with downward rounding in the case that the byte 
count is not a page multiple. For example, if the page size is 2048, then 
btop (4096) returns 2, and btop (4097) returns 2 as well. btop(O) returns 
0. 

RETURN VALUE 

The return value is always the number of pages. There are no invalid input 
values, and therefore no error return values. 

LEVEL 

Base or Interrupt 

SEE ALSO 

btopr(D3DK), ptob(D3DK) 
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NAME 

btopr - convert size in bytes to size in pages (round up) 

SYNOPSIS 

♦include <sys/ddi.h> 

unsigned long btopr (unsigned long numbytes) ; 

ARGUMENT 

nunibytes Number of bytes. 

DESCRIPTION 

This function returns the number of memory pages contained in the specified 
number of bytes memory, rounded up to the next whole page. For example, if 
the page size is 2048, then btopr (4096) returns 2, and btopr (4 097) returns 
3. 

RETURN VALUE 

The return value is always the number of pages. There are no invalid input 
values, and therefore no error return values. 

LEVEL 

Base or Interrupt 

SEE ALSO 

btop(D3DK), ptob(D3DK) 
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NAME 

buf call - call a function when a buffer becomes available 

SYNOPSIS 

♦include <sys/stream.h> 

int bufcalKint size, int pri, int {*func) {) , long arg) ; 

ARGUMENTS 

size Number of bytes in the buffer. 

pri Priority of the allocb(D3DK) allocation request (not used). 

func Function or driver routine to be called when a buffer becomes avail- 
able. 

arg Argument to the fimction to be called when a buffer becomes avail- 

able. 

DESCRIPTION 

buf call serves as a timeout (D3DK) call of indeterminate length. When a 
buffer allocation request fails, buf call can be used to schedule the routine func, 
to be called with the argument arg when a buffer becomes available, func may be 
a routine that calls buf call or it may be another kernel fimction. 

NOTE: Even when func is called by buf call, allocb(D3DK) can still fail if 
another module or driver had allocated the memory before func was able to call 
allocb. 

RETURN VALUE 

If the buf call scheduling fails, func is never called and 0 is returned. If suc- 
cessful, buf call returns 1. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 

allocb(D3DK), esballoc(D3DK), esbbcall(D3DK), testb(D3DK), 
timeout(D3DK) 

EXAMPLE 

The purpose of this srv(D2DK) service routine is to add a header to all M_DATA 
messages. Service routines must process all messages on their queues before 
returning, or arrange to be rescheduled. 

While there are message to be processed (line 13), check to see if it is a high 
priority message or a normal priority message that can be sent on (line 14). Nor- 
mal priority message that cannot be sent are put back on the message queue (line 
34). If the message was a high priority one, or if was normal priority and 
canput(D3DK) succeeded, then send all but M__DATA messages to the next 
stream entity with putnext(D3DK) (linel6). 

For M^DATA messages, try to allocate a buffer large enough to hold the header 
(line 18). If no such buffer is available, the service routine must be rescheduled 
for a time when a buffer is available. The original message is put back on the 
queue (line 20) and buf call (line 21) is used to attempt the rescheduling. It 
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will succeed if a biiffer of the specified size (sizeof (struct hdr)) is avail- 
able. If it does, qenable(D3DK) will put q on the list of queues to have their 
service routines called. If bufcall fails, timeout(D3DK) (line 22) is used to 
try again in about a half second (HZ/2). 

If the buffer allocation was successful, initialize the header (lines 25-28), make the 
message type M_PROTd (line 29), link the M_DATA message to it (line 30), and 
pass it on (line 31). 

1 struct hdr { 



2 unsigned int h_size; 

3 int h_version; 

4 }; 

6 modsrv (q> 

7 queue_t *q; 

8 { 

9 mblk__t *bp; 

10 mblk__t *inp; 

11 struct hdr *hp; 
12 

13 while ((mp - getq(q)> !- NULL) { /* get next message */ 

14 if (inp->b_datap->db_type >- QPCTL i | /* if high priority */ 

cahput (q->c[_next ) > { /* normal & can be passed */ 

15 if (mp~>b_datap->db_type !- M_DATA) 

16 putne:ct(q, mp) ; /* send all but M_DATA */ 

17 else { 

18 bp - allocb (sizeof (struct hdr) , BPRI_LO) ; 

19 if (bp — NULL) { /* if unsuccessful */ 

20 putbq(q, mp) ; /* put it back */ 

21 if (! bufcall (sizeof (struct hdr), BPRI_LO, 

qenable, (long)q)) /* try to reschedule */ 

22 timeout (qenable, (long)q, HZ/2) ; 

23 return; 

24 ) 

25 hp - (struct hdr *) bp->b_wptr; 

26 hp->h_si2e - msgdsize (mp) ; /* initialize header */ 

27 hp->h_version - 1; 

28 bp->b_wptr +- sizeof (struct hdr); 

29 bp->b__datap->db__type - M_PROTO; /* make M_PROTO */ 

30 bp->b_cont - mp; /* link it */ 

31 putnext(q, bp); /* pass it on */ 

32 } 

33 ) else { /* normal priority, canput failed */ 

34 putbq(q, mp) ; /* put back on the message queue */ 

35 return; 

36 ) 

37 } 

38 } 
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NAME 

bzero - clear memory for a given number of bytes 

SYNOPSIS 

♦include <sys/types . h> 

int hzero {caddrjtaddr, int bytes) / 
ARGUMENTS 

addr Starting virtual address of memory to be cleared. 
bytes The number of bytes to clear starting at addr. 
DESCRIPTION 

The bzero function clears a contiguous portion of memory by filling the 
memory with zeros. 

CAUTION: The address range specified must be within the kernel space. No 
range checking is done. If an address outside of the kernel space is selected, the 
driver may corrupt the system in an unpredictable way. 

RETURN VALUE 

Under normal conditions, a 0 is returned. Otherwise, a -1 is returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

bcopy(D3DK), clrbuf(D3DK), kmem_zalloc(D3DK) 
EXAMPLE 

In a driver close(D2DK) routine, rather than clear each individual member of 
its private data structure, the driver could use bzero as shown here: 

bzero (&drv_dat [minor (dev) ] , sizeof (struct drvr_data) ) ; 



3-24 



10/89 



Canput(D3DK) 



canput(D3DK) 



NAME 

danput - test for room in a message queue 

SYNOPSIS 

# include <sys /stream . h> 

int canput (queue_t *cq) ; 
ARGUMENT 

*c(i The pointer to the message queue. queue_t is an alias for the 

queue(D4DK) structure. 

DESCRIPTION 

canput searches through the stream (starting at ccj) until it finds a queue contain- 
ing a service routine where the message can be enqueued, or until it reaches the 
end of the stream. If found, the queue containing the service routine is tested to 
see if there is room for a message in the queue. If the queue is full, canput sets 
the QWANTW flag to back-enable the caller's service routine. 

NOTE: You are responsible for both testing a queue with canput and refraining 
from placing a message on the queue if canput fails. 

RETURN VALUE 

If the message queue is not full, 1 is returned. A 0 is returned if the queue is 
full. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
bcanput(D3DK), putbq(D3DK), putnext(D3DK) 
EXAMPLE 

See the buf call(D3DK) function page for an example of canput. 
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NAME 

clrbuf - erase the contents of a buffer 

SYNOPSIS 

finclude <sys/types.h> 
♦include <sys/buf .h> 

void clrbuf (struct buf ^^bp) ; 
ARGUMENT 

*bp Pointer to the buf (D4DK) structure 

DESCRIPTION 

The clrbuf function zeros a buffer and sets the b_resid member of the buf 
structure to 0. 2feros are placed in the buffer starting at bp->b_un. bywords 
for a length of bp->bjDGount bytes. b_un.b_words and b_bcount are 
members of the buf structure defined in sys/buf .h. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 

SEE ALSO 

brelse(D3DK), buf(D4DK) 

EXAMPLE 

See biowait(D3DK). 
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NAME 

cxnn__err - display an error message or panic the system 

SYNOPSIS 

♦include <sys/cinn_err .h> 

int cmn^err ( int level, char ^format, int orgs) ; 
ARGUMENTS 

level A constant defined in the sys/cmn_err . h header file, level indicates 
the severity of the error condition. The four severity levels are 

CE_CONT used to continue another message or to display an 
informative message not connected with an error. 

CE_NOTE used to display a message preceded with NOTICE. 

This message is used to report system events that do 
not necessarily require user action, but may interest the 
system administrator. For example, a message saying 
that a sector on a disk needs to be accessed repeatedly 
before it can be accessed correctly might be 
noteworthy. 

CE__WARN used to display a message preceded with WARNING. 

This message is used to report system events that 
require immediate attention, such as those where if an 
action is not taken, the system may panic. For exam- 
ple, when a peripheral device does not initialize 
correctly, this level should be used. 

CE_PANIC used to display a message preceded with PANIC or 
DOUBLE PANIC, and to panic the system. Drivers 
should specify this level only under the most severe 
conditions or when debugging a driver. A valid use of 
this level is when the system cannot continue to func- 
tion. If the error is recoverable, or not essential to con- 
tinued system operation, do not panic the system. This 
level halts multiuser processing. 

format The message to be displayed. By default, the message is sent both to 
the system console and to the kernel buffer putbuf . If the first char- 
acter in format is an exclamation point (" ! "), the message goes only to 
putbuf. If the first character in format is a circumflex ("^"), the mes- 
sage goes only to the console. Except for the first character, the rules 
for format are the same as those for printf(3S) strings. To read put- 
buf, use the following crash(lM) commands: 

od -d putbuf sz 
od -a putbuf size 

The first command returns the size of putbuf (the default is 2000 
bytes). The second command uses the returned size to read putbuf. 
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cinn_err appends \n to each format, even when a message is sent to 
putbuf, except when level is CE_CONT. 

Vaild conversion specifications are %a, %u, %d, %o, and %x. The cmn_err 
function is otherwise similar to the printf (3S) library subroutine in displaying 
messages on the system console or storing on putbuf . 

NOTE: cmn^err does not accept length specifications in conversion 
specifications. For example, %3d is ignored. 

args the set of arguments passed with the message being displayed. Any 
argument within the range of supported conversion specifications can 
be passed. 

DESCRIPTION 

cmn__err displays a specified message on the console and /or stores it in the 
putbuf array, cmn^err can also panic the system. 

At times, a driver may encounter error conditions requiring the attention of a pri- 
mary or secondary system console monitor. These conditions may mean halting 
multiuser processing; however, this must be done with caution. Except during 
the debugging stage, a driver should never stop the system. 

The cmnjerr function with the CE_CONT argument can be used by driver 
developers as a driver code debugging tool. However, using cnvn^err in this 
capacity can change system timing characteristics. 

If CEJPANIC is set, cmn_err stops the machine. 

RETURN VALUE 

None. However, if an unknown level is passed to cmn^err, the following panic 
error message is displayed: 

PANIC: unknown level in cmn_err {level-level, msg^fortmt) 

LEVEL 

Base or Interrupt 

SEE ALSO 

BCI Driver Development Guide, Oiapter 12 

print(D2DK), printf(3S) 
EXAMPLE 

The cinn_err function can record tracing and debugging information only in the 
putbuf (lines 15 and 16); display problems with a device only on the system con- 
sole (line 21); or stop the system if a required device malfunctions (line 27). 

1 struct device { /* physical device registers layout */ 



2 Int control; /* physical device control word */ 

3 Int status; /* physical device status word */ 

4 Int error; /* error codes from device */ 

5 short recv__char; /* receive character from device */ 

6 short xmit^char; /* transmit character to device */ 



7 ); /* end device */ 
8 

9 extern struct device xx_addr[]; /* physical device registers */ 

10 extern int xx__cnt; /* number of physical devices */ 
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11 register struct device *rp; 

12 rp " xx_addr [ (getminor (dev) » 4) 4 Oxf]; /* get dev registers */ 
13 

14 iifdef DEBUG /* in debugging mode, log function call */ 

15 cinn_err(CE_NOTE, "!xx_open function call, dev - Ox%x'*, dev) ; 

16 cinn_err (CE__CONT, "! flag - Ox%x", flag); /* continue msg */ 

17 lendif /* end DEBUG */ 
18 

19 /* display device power failure on system console */ 

20 if ((rp->status & POWER) — OFF) 

21 cmn_jerr (CE__WARN, "xx^open: Power is OFF on device %d port %d'*, 

22 ( (getminor (dev) » 4) & Oxf), (getminor (dev) & Oxf ) ) ; 
23 

24 /* halt system if root device has bad VTOC */ 

25 /* send message to system console and to putbuf */ 

26 if (rp->error -« BADVTOC && dev — rootdev) 

27 cmn_jerr (CE_PANIC, "xx__open: Bad VTOC on root device"); 
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NAME 

copyb - copy a message block 

SYNOPSIS 

♦include <sys/ stream. h> 

inblk_t *copyb(xnblk_J: *bp) ; 
ARGUMENT 

bp Pointer to the message block from which data is copied. 

DESCRIPTION 

copyb allocates a new message block, and copies into it the data from the block 
pointed to by bp. The new block will be at least as large as the block being 
copied. The b_rptr and b_wptr members of bp are used to determine how 
many bytes to copy. 

RETURN VALUE 

If successful, copyb returns a pointer to the newly allocated message block con- 
taining the copied data. Otherwise, it returns a NULL pointer. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
allocb(D3DK) 
EXAMPLE 

For each message in the list, test to see if the downstream queue is full with the 
canput(D3DK) function (line 21). If it is not full, use copyb(D3DK) to copy a 
header message block, and dupmsg(D3DK) to duplicate the data to be 
retransmitted. If either operation fails, reschedule a timeout at the next valid 
interval. 

Update the new header block with the correct destination address (line 34), link 
the message to it (line 35), and send it downstream (line 36). At the end of the 
list, reschedule this routine. 

1 struct retms { 

2 mblk__t *r_inp; 

3 long r_address; 

4 queue_t *r_outq; 

5 struct retrns *r__next; 

6 }; 
7 

8 struct protoheader { 

9 long h_address; 

10 }; 
11 

12 inblk__t *header; 
13 

14 retransmit (ret) 
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15 register struct retms *ret; 

16 { 

17 register inblk__t *bp, *inp; 

18 struct protoheader *php; 
19 

20 while (ret) ( 

21 if ( Icanput (ret->r__outq->q_next) ) { /* no room */ 

22 ret - ret->r__next; 

23 continue; 

24 } 

25 bp - copyb (header) ; /* copy header msg. block */ 

26 if (bp — NULL) 

27 break; 

28 mp - dupinsg(ret->r_inp) ; /* duplicate data */ 

29 if (mp —NULL) { /* if unsuccessful */ 

30 freeb(bp); /* free the block */ 

31 break; 

32 } 

33 php - (struct protoheader *)bp->b_rptr; 

34 php->h_address - ret->r__address; /* new header */ 

35 bp->bp_cont - mp; /* link the message */ 

36 putnext (ret->r_outq, bp); /* send downstream */ 

37 ret - ret-->r_jiext; 

38 ) 

39 timeout (retransmit, (long) ret, RETRNS_TIME) ; /* reschedule */ 

40 ) 
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NAME 

copyin - copy data from a user program to a driver buffer 

SYNOPSIS 

♦include <sys/types .h> 

int copyin (caddr_t userhuf, caddr_t driverbuf, int cn) ; 
ARGUMENTS 

userhuf User program source address from which data is transferred. 
driverbuf Driver destination address to which data is transferred. 
cn Number of bytes transferred. 

DESCRIPTION 

copyin copies data from a user program source address to a driver buffer. The 
driver developer must ensure that adequate space is allocated for the destination 
address. 

Addresses that are word-aligned are moved most efficiently. However, the driver 
developer is not obligated to ensure alignment. This fimctioii automatically finds 
the most efficient move according to address alignment. 

RETURN VALUE 

Under normal conditions a 0 is returned indicating a successful copy. A -1 is 
returned if one of the following occurs: 

paging fault; the driver tried to access a page of memory for which it did 
not have read or write access 

invalid user area or stack area 

invalid address that would have resulted in data being copied into the 
user block 

If a -1 is returned, return EFAULT- 

LEVEL 

Base Only (Do not call from an interrupt routine) 
SEE ALSO 

BCl Driver Devehpment Guide, Chapter 6, "Input/Output Operations" 
bcopy(D3DK), copyout(D3DK), uiomove(D3DK) 
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NAME 

copymsg - copy a message 

SYNOPSIS 

♦include <sys/stream.h> 

inblk_t *copyinsg (inblk_t mp) ; 
ARGUMENTS 

mp Pointer to the message to be copied. xnblk_t is an instance of the 

msgb(D4DK) structure. 

DESCRIPTION 

cbpymsg forms a new message by allocating hew message blocks, copies the con- 
tents of the message referred to by mp (using the copyb(D3DK) function), and 
returns a pointer to the new message. 

RETURN VALUE 

If the copy is successful, copyxn^g returns a pointer to the new message. Other- 
wise, it returns a NULL pointer. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
allocb(D3DK), copyWDSDK), msgb(D4DK) 
EXAMPLE 

The routine Ictouc converts all the lowercase ASQI characters in the message to 
uppercase. If the reference count is greater than one (line 8), then the message is 
shared, and must be copied before changing the contents of the data buffer. If 
the call to the copymsg(D3DK) function fails (line 9), return NULL (line 10), oth- 
erwise, free the original message (line 11). If the reference count was equal to 1, 
the message can be modified. For each character (line 16) in each message block 
(line 15), if it is a lowercase letter, convert it to an uppercase letter line 18). A 
pointer to the converted message is returned (line 21). 



1 inblk_t *lctouc(mp) 

2 mblkjt *mp; 

3 { " J... V :■ :{ 

4 inbllc_t *cihp; 

5 inblk__t *tnip; 

6 unsigned char *cp; 
7 

8 If (inp->b__datap->db_ref > 1) { 

9 if ( (canp - copymsg (mp) ) -- NULL) 

10 return (NqLL); 

11 freemsgCmp); 

12 } else { 

13 cmp - mp; 

14 } 

15 for (tihp - cmp; tmp; tmp » tmp->b_next) { 

16 for (cp - tmp->b_rptr; cp < tmp->b__wptr; cp++) { 
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17 if ((*cp <- 'z') £& 

18 *cp — 0x20; 

19 ) 

20 ) 

21 return (cmp) ; 

22 } 



copymsg (D3DK) 

(*cp >- 'a')) 
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NAME 

copyout - copy data from a driver to a user program 

SYNOPSIS 

♦include <sys/types .h> 

int copyout (caddr_t driverbuf, caddr_t userbuf, long cn) ; 
ARGUMENTS 

driverbuf Source address in the driver from which the data is transferred. 

userbuf Destination address in the user program to which the data is 
transferred. 

cn Number of bytes moved. 

DESCRIPTION 

copyout copies data from driver buffers to user data space. 

Addresses that are word-aligned are moved most efficiently. However, the driver 
developer is not obligated to ensure alignment. This function automatically finds 
the most efficient move algorithm according to address alignment. 

RETURN VALUE 

Under normal conditions a 0 is returned to indicate a successful copy. Other- 
wise, a -1 is returned if the specified address range is not valid. 

If a -1 is returned, return EFAULT. 

LEVEL 

Base Only (Do not call from an interrupt routine) 
SEE ALSO 

BCI Driver Development Guide, Chapter 6, "Input/Output Operations" 
bcopy(D3DK), uioinove(D3DK), copyin(D3DK) 
EXAMPLE 

A driver ioctl(D2DK) routine (line 9) can be used to get or set device attributes 
or registers. In the XX__GETREGS condition (line 17), the driver copies the current 
device register values to a user data area (line 18). If the specified argument con- 
tains an invalid address, an error code is returned. 



1 


struct device { /* layout 


of physical device registers 


*/ 


2 


int control; /* 


physical device control word 


*/ 


3 


int status; /* 


physical device status word 


*/ 


4 


short recv_char; /* 


receive character from device 


*/ 


5 


short xmit__char; /* 


transmit character to device 


*/ 


6 


}; /* end device */ 






7. 
8 


extern struct device xx__addr(]; > 


^* phys. device regs. location 


*/ 


9 


xx__ioctl (dev, cind, arg, flag) 






10 


dev_t dev; 






11 


caddr__t arg; 






12 








13 


{ 






14 


register struct device *rp - 


&xx_addr [getminor(dev) » 4]; 
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15 switch (cmd) ( 
16 

17 case XX_GETREGS: /* copy device regs. to user program */ 

18 if (copyout ( (caddr_t)rp, arg, slzeof (struct device)) 

19 return (EFAULT) ; 

20 /* endif */ 

21 break; 
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NAME 

datamsg - test whether a message is a data message 

SYNOPSIS 

#include <sys/stream.h> 
♦include <sys/ddi.h> 

int datamsg (unsigned char type); 
ARGUMENT 

type The type of message to be tested. The db_type field of the datab 
structure contains the message type. This field may be accessed 
through the message block using nip->b_datap->db_type. 

DESCRIPTION 

The datamsg function tests the type of message to determine if it is a data mes- 
sage type (M_DATA, M_DELAY, M_PROTO, or M_PCPROTO). 

RETURN VALUE 

datamsg returns 1 for TRUE, if the message is a data message; and 0 for 
FALSE for any other type of message. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
allocb(D3DK), datab(D4DK), msgb(D4DK) 
EXAMPLE 

The put(D2DK) routine enqueues all data messages for handling by the 
srv(D2DK) (service) routine. All non-data messages are handled in the put rou- 
tine. 

1 xxxput(q, mp) 

2 queue_t *q; 

3 inblk_t *mp; 

4 { 

5 if (datamsg (inp->b__datap->db__type) ) { 

6 putq(q, mp> ; 

7 return; 

8 } 

9 switch (inp->b_datap->db_type) { 

10 case M_FLUSH: 

11 ) 

12 } 
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NAME 

delay - delay process execution for a specified number of clock ticks 

SYNOPSIS 

void delay (long ticks); 

ARGUMENT 

ticks The number of clock cycles for a delay, ticks are frequently set as an 
expression containing the system variable HZ, the number of clock 
ticks in one second; HZ is defined in sys/param.h. 

DESCRIPTION 

delay provides a way to wait for an event to happen. Occasionally, a driver 
may need to wait a given period of time until work is available. The value of HZ 
can vary from system to system, and so the function drv_hztousec(D3DK) 
should be used when accurate timing is required. 

The delay function calls timeout(D3DK) to schedule a wakeup call after the 
specified amount of time has elapsed, delay then goes to sleep imtil timeout 
wakes up the sleeping process. While delay is active, splhi is set. At comple- 
tion, the former priority level is returned through splx. 

delay requires user context. 

RETURN VALUE 

None 

LEVEL 

Base Only (Do not call from an interrupt routine) 
SEE ALSO 

BCI Driver Development Guide, Chapter 10, "Synchronizing Hardware and 
Software Events" 

biodone(D3DK), biowait(D3DK), drv_hztousec(D3DK), 
drv_usectohz(D3DK), sleep(D3DK), timeout (D3DK), untimeout(D3DK), 
wakeup(D3DK) 

EXAMPLE 

Before a driver I/O routine allocates buffers and stores any user data in them, it 
checks the status of the device (line 12). If the device needs manual intervention 
(such as, needing to be refilled with paper), a message is displayed on the system 
console (line 14). The driver waits an allotted time (line 16) before repeating the 
procedure. 

1 struct device { /* layout of physical device registers */ 

2 int control; /* physical device control word */ 

3 int status; /* physical device status word */ 

4 short xmit__char; /* transmit character to device */ 

5 }; /* end device */ 
6 

7 extern struct device xx__addr[]; /* physical device regs. location */ 

9 /* get device registers */ 

10 register struct device *rp - &xx__addr[getininor (dev>»4) ] ; 
11 
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12 while (rp->5tatus & NOPAPER) { /* while printer is out of paper */ 

13 /* display message and ring bell on system console */ 

14 cmn__err(CE_WARN, •"^xx_write: NO PAPER in printer %d\007", 

15 (dev & Oxf)); 

16 delay (60 ♦ HZ); /* wait one minute and try again */ 

17 ) /* endwhile */ 
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NAME 

diina_j>ageio - break up an I/O request into manageable units 

SYNOPSIS 

tinclude <sys/buf .h> 

void dxnajpageio ( void (*strat) () strot, struct buf *bp) ; 
ARGUMENTS 

*strat Pointer to the strategy(D2DK) routine to call to complete the I/O 
transfer. 

bp Pointer to the buf structure. 

DESCRIPTION 

dma^jpageio breaks up a data transfer request from physiock(D3DK) into units 
of contiguous memory. This function enhances the capabilities of the direct 
memory access controller (DMAC). The data is broken into 512-byte sectors until 
the last data bytes are encountered, dma^ageio executes splO around its 
internal sleep calls on reads and writes after the strategy routine is called. 
This may alter previously set spl(D3D) calls. 

The driver must modify b_f lags to indicate whether the transfer is a read or a 
write. OR in BJREAD to indicate a read; turn B_READ off to indicate a write. 

RETURN VALUE 

None. However, conditions in dmajpageio can cause the following to be set: 

If memory for a temporary buffer cannot be allocated, b__f lags is ORed 
with B__ERROR and B_pONE, and b^error is set to EAGAIN (resource 
temporarily imavailable). All allocated temporary buffers are deallocated 
when the transfer completes. 

If the I/O transfer is incomplete (b__f lags does not contain B^DONE), 
then b_flags is set to B_WANTED and sleep(D3DK) is called to wait 
until a buffer can be allocated. The sleep priority is set to PRIBIO. 

The sleep code section is surrounded by a spl6-spl0 function set 
which may alter a previously set spl value. 

If B_ERROR is set after the strategy(D2DK) routine completes, allo- 
cated memory is freed and dmajpageio returns. 

When the transfer completes, any allocated buffers are freed. 

LEVEL 

Base Only 
SEE ALSO 

BCI Driver Development Guide, Chapter 6, "Input/Output Operations" 
EXAMPLE 

The following example shows how dmajpageio is used when reading or writ- 
ing disk data. 

1 struct dslze { 

2 daddr_t nblocks; /* number of blocks in disk partition */ 

3 iht cyloff ; /* starting cylinder # of partition */ 

4 ) iny_sizes[4] - { 
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5 

6 20448, 21, /* partition 0 - cyl 21-305 */ 

7 21888, 1 /* partition 1 - cyl 1-305 */ 

8 }; 
9 

10 /* physical read */ 

11 iny_read(dev, uio__P/ cred_p) 

12 dev_t dev; 

13 uio_t *uio_j>; 

14 cred__t *cred_j>; 

15 { 

16 register int nblks; 

17 /* get number of blocks in the partition */ 

18 nblks - iny__sizes [getminor (dev) & 0x7] .nblocks; 
19 

20 if request is within limits for the device, schedule I/O*/ 

21 physiock(my_breakup, 0, dev, B__REAP, nblks, uio_p) ; 
22 

23 } 

24 /* physical Write */ 

25 my__write(dev, uio__p, cred_p> 



26 dev_t dev; 

27 uio_t *uio_p; 

28 cred_t *cred_p; 

29 { 

30 register int nblks; 

31 /* get the number of blocks in the partition */ 

32 nblks - iny_si2es [getminor (dev) & 0x7] .nblocks; 
33 

34 /* if request is within limits for the device, schedule I/O */ 

35 physiock (my__breakup, 0, dev, B_WRITE, nblks, uio__p); 

36 } 

37 } 

38 /* 

39 * break up the request that came from physio into Chunks of 

40 * contiguous memory. Pass at least 512 bytes (one sector) at a 

41 * time (except for the last request). 



42 */ 
43 

44 static 

4 5 my__brea kup ( bp ) 

46 register struct buf *bp; 

47 { 

48 dma_j)ageio (my_strategy, bp); 

49 } 
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NAME 

drv_getparm - retrieve kernel state information 

SYNOPSIS 

♦include <sys/ddi.h> 

int drv_getparm(unsigned long parm, unsigned long ^valuej)) ; 
ARGUMENTS 

jxxrm The kernel parameter to be obtained from ddi ,h. Possible values are 

LBOLT Read the value of the Ibolt. (Ibolt is an integer that 
represents the number of clock ticks since the last system 
reboot. This value is used as a counter or timer inside 
the system kernel.) 

PPGRP Read the process group identification number. This 
number determines which processes should receive a 
HANGUP or BREAK signal when detected by a driver. 

UPROCP Read the process table token value. This information is 
used for the second argument of the vtop(D3D) func- 
tion. 

PPID Read process identification ntimber. 

PS ID Read process session identification number. 

TIME Read time in seconds. 

value J) A pointer to the data space in which the value of the parameter is to 
be copied. 

DESCRIPTION 

This function verifies that parm correspond! to a kernel parameter that may be 
read. If the value of parm does not correspond to a parameter or corresponds to 
a parameter that may not be read, -1 is returned. Otherwise, the value of the 
parameter is stored in the data space pointed to by value_p. 

drv_getparm does not explicitly check to see whether the device has the 
appropriate context when the function is called and the function does not check 
for correct alignment in the data space pointed to by value j). It is the responsi- 
bility of the driver writer to use this function only when it is appropriate to do so 
and to correctly declare the data space needed by the driver. 

RETURN VALUE 

drv_getparm returns 0 to indicate success, -1 to indicate failure. The value 
stored in the space pointed to by value j) is the value of the parameter if 0 is 
returned, undefined if -1 is returned. -1 is returned if you specify a value 
other than LBOLT, PPGRP, PPID, PS ID, TIME or UPROCP. Always check 
the return code when using this function. 



LEVEL 



Base only when using the PPGRP, PPID, PSID, TIME, or UPROCP argument 
values. 
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Interrupt usable when using the LBOLT argument value. 

SEE ALSO 

vtop(D3D), buf (D4DK) 
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NAME 

drv_hztousec - convert clock ticks to microseconds 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/ddi.h> 

clock_t drv_hztousec (clock__t hz) ; 
ARGUMENT 

hz The length of time (expressed in HZ imits) to convert to its 

microsecond equivalent 

DESCRIPTION 

drv_hztousec converts into microseconds the length of time expressed by hz, 
which is in units of time based on the value of HZ, the kernel parameter whose 
value is defined in sys/param.h. 

The kernel variable Ibolt, which is readable through drv_getparin(D3DK), is 
the length of time the system has been up since boot and is expressed in HZ 
units. Drivers often use the value of Ibolt before and after an I/O request to 
measure the amount of time it took the device to process the request. 
drv_hztousec can be used by the driver to convert the reading from HZ units, 
which could potentially vary between system implementations, to a known unit 
of time. 

RETURN VALUE 

The number of microseconds equivalent to the hz argument. No error value is 
returned. If the microsecond equivalent to hz is too large to be represented as a 
clock_t, then the maximim\ clock_J: value will be returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

drv_getparxn(D3DK), drv_usectohz(D3DK) 
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NAME 

drv_priv - determine driver privilege 

SYNOPSIS 

int drvjpriv (credit *cr) ; 

ARGUMENT 

*cr Pointer to the cred(D4DK) (credential) structure. 

DESCRIPTION 

The drv__priv function provides a general interface to the system privilege pol- 
icy. It determines whether the credentials supplied by the cred structure 
pointed to by cr identify a priviledged process. This fimction should only be 
used when file access modes and special minor device numbers are insufficient to 
provide protection for the requested driver function. It is intended to replace all 
calls to suserO and any explicit checks for effective user ID * 0 in driver 
code. 

RETURN VALUE 

This routine returns 0 if it succeeds, EPERM if it fails. 

LEVEL 

Base or Interrupt 

SEE ALSO 

cred(D4DK) 
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NAME 

drv_usectohz - convert microseconds to clock ticks 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/ddi.h> 

docket drv_usectohz (clock_t microsecs) ; 
ARGUMENTS 

microsecs The number of microseconds to convert to its HZ equivalent. 
DESCRIPTION 

drv__usectohz converts a length of time expressed in microseconds to HZ, the 
unit of time based on the the kernel parameter HZ whose value is defined in 
sys/param.h. The time arguments to timeout (D3DK) and delay(D3DK) are 
expressed in HZ, as well as the kernel variable Ibolt, which is readable through 
drv_getparin(LBOLT) . 

drv__usectohz is a portable way for drivers to make calls to timeout (D3DK) 
and delay(D3DK) and remain binary compatible should the driver object file be 
made part of a kernel that was compiled with a value of HZ different from that 
with which the driver was compiled. 

RETURN VALUE 

The value returned is the number of HZ units equivalent to the microsecs argu- 
ment. No error value is returned. If the HZ equivalent to microsecs is too large to 
be represented as a clock__t, then the maximum clock_t value will be 
returned. 

LEVEL 

Base or Interrupt 

SEE ALSO 

drv hztousec(D3DK) 
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NAME 

drv_usecwait - busy-wait for specified interval 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/ddi.h> 

void drv_usecwait (clock_t microsecs) t 
ARGUMENT 

microsecs The number of microseconds to busy-wait. 
DESCRIPTION 

The kernel fimction delay(D3DK) can be used by a driver to delay for a 
specified number of system ticks (given by parameter HZ in sys/param.h, 
which indicates how many system ticks occur per second). There are two limita- 
tions: (1) the granularity of the wait time is limited to 1/HZ second, which may 
be more time than is needed for the delay, and (2) delay(D3DK) may only be 
invoked with user context and hence cannot be used at interrupt time or system 
initialization. 

Often, drivers need to delay for only a few microseconds, waiting for a write to a 
device register to be picked up by the device. In this case, even with user context, 
delay(D3DK) produces too long a wait period. The function drv__usecwait is 
provided to give drivers a means of busy-waiting for a specified microsecond 
count. The amount of time spent busy-waiting may be greater than the 
microsecond count but will minimally be the number of microseconds specified. 

Note that the driver wastes processor time by making this call since 
drv_usecwait does not invoke sleep but simply busy- waits. The driver should 
only make calls to drv_usecwait as needed, and only for as much time as 
needed. drv_usecwait does not raise the processor interrupt level; if the 
driver wishes to mask out interrupts, it is its responsibility to set the priority level 
before the call and restore it to its original value afterward. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

delay(D3DK), timeout(D3DK), untimeout(D3DK) 
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NAME 

dupb - duplicate a message block descriptor 

SYNOPSIS 

♦include <sys/stream.h> 

mblk_t *dupb(xnblk_t *bp) ; 
ARGUMENTS 

*bp Pointer to the ntessage block to be duplicated. inblk_t is an instance 

of the insgb(D4DK) structure. 

DESCRIPTION 

dupb creates a new iriblk_t structure to reference the message block pointed to 
by bp. Unlike copyb(D3DK), dupb does not copy the information in the data 
block, but creates a new structure to point to it. 

The following figure shows how the db_ref field of the dblk_t structure has 
been changed from 1 to 2, reflecting the increase in the number of references to 
the data block. The new inblk_t contains the same information as the first. 
Note that b_rptr and b__wptr are copied from bp, and that db_ref is incre- 
mented. 



db_ref 
db_base 


(1) 


A 






Before 



bp 



db_ref (2) 
db base 



b^^datap 

b^rptr 
~i b_wptr 



nbp 



b_datap 

b__rptr 
b_wptr 



After 



nbp-dupb (bp) ; 

RETURN VALUE 

If successful, dupb returns a pointer to the new message block. Otherwise, it 
returns a NULL pointer. 

LEVEL 

Base or Interrupt 

SEE ALSO 

Gopyb(D3DK) 
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EXAMPLE 

This srv(D3DK) (service) routine adds a header to all MJ)ATA messages before 
passing them along. The message block for the header was allocated elsewhere. 
For each message on the queue, if it is a priority message, pass it along immedi- 
ately (line3 9-10). Otherwise, if it is anything other than an M_DATA message 
(line 11), and if it can be sent along (line 12), then do so (line 13). Otherwise, put 
the message back on the queue and return (lines 15-16). For all M_DATA mes- 
sages, first check to see if the stream is flow-controlled (line 19). If it is, put the 
message back on the queue and return (line 22); if it is not, the header block is 
duplicated (line 20). If dupb fails, the service routine is rescheduled in one tenth 
of a second (HZ/ 10) with timeout and then we return (lines 23-24). If dupb 
succeeds, link the M_DATA message to it (line 26) and pass it along (line 27). 
dupb can be used here instead of copyb(D3DK) because the contents of the 
header block are not changed. 



1 xxxsrv(q) 

2 queue_t *q; 

3 { 

4 inblk_t *inp; 

5 inblk__t *bp; 

6 extern inbllc_t *hdr; 
7 

8 while ((mp - getq(q>) !- NULL) { 

9 if (inp->b_datap->db_type >- QPCTL) { 

10 putnext(q, mp) ; 

11 } else if (inp->b_<Jatap->db_type I- M_DATA) { 

12 if (canput (q->q_next)) 

13 put next (q, mp) ; 

14 else { 

•1-5 putbqCq, jnp); 

16 return; 

17 } 

18 } else { /* M_DATA */ 

19 if (canput (q->q_next) ) { 

20 bp - dupb(hdr); 

21 if (bp — NULL) { 

22 putbq(q, mp); 

23 timeout (qenable, (long)q, HZ/10); 

24 return; 

25 } 

26 linkb(bp, mp) ; 

27 putnext(q, bp); 

28 } else { 

29 putbq(q, mp) ; 

30 return; 

31 ) 

32 ) 

33 ) 

34 } 
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NAME 

dupmsg - duplicate a message 

SYNOPSIS 

♦include <sys/stream.h> 

inblk_t * dupmsg (inblk_t *mp) ; 

ARGUMENTS 

mp Pointer to the message block, 

DESCRIPTION 

dupmsg fonns a new message by copying the message block descriptors pointed 
to by mp and linking them. dupb(D3DK) is called for each message block. The 
data blocks themselves are not duplicated. 

RETURN VALUE 

If successful, dupmsg returns a pointer to the new message block. Otherwise, it 
returns a NULL pointer. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
copyb(D3DK), copymsg(D3DK), dupb(D3DK) 
EXAMPLE 

See the copyb(D3DK) function page for an example of dupmsg. 
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NAME 



enableok - reschedule a queue for service 



SYNOPSIS 



♦include <sys/stream.h> 
♦include <sys/ddi.h> 

void enableok (queue__t *q) ; 



ARGUMENT 



A pointer to the queue to be rescheduled. 



DESCRIPTION 

The enableok function allows queue q to be rescheduled for service. It cancels 
the effect of a previous use of the noenable(D3DK) function on q by turning off 
the QNOENB flag in the queue. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
noenable(D3DK), qenable(D3DK) 
EXAMPLE 

The qrestart routine uses two STREAMS functions to restart a queue that has 
been disabled. The enableok function turns off the QNOENB flag, allowing the 
qenable(D3DK) function to schedule the queue for immediate processing. 

1 void 

2 qrestart (rdwr_jq) 

3 register queue__t *rdwr_q; 



4 



5 { 
6 



enableok (rdwr_q) ; 

/* re-enable a queue that has been disabled */ 
(void) qenable (rdwr__q) ; 



7 



8 
9 

10 ) 
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NAME 

esballoc - allocate a message block using a shared buffer 

SYNOPSIS 

♦include <sys/stream.h> 

inblk_t *esballoc (unsigned char *base, int size, int pri, 
f rtn_t *fr_rtnp) ; 

ARGUMENTS 

base Address of user supplied data buffer. 

size Number of bytes in data buffer. 

pri Priority of allocation request (to be used by allocb(D3DK) function, 

called by esballoc). 

frjrtnp Free routine data structure. 

DESCRIPTION 

esballoc creates a STREAMS message and attaches a user-supplied data buffer 
in place of a STREAMS data buffer. It calls allocb(D3DK) to get a message and 
data block header only. The user-supplied data buffer, pointed to by base, is used 
as the data buffer for the message. 

The f ree__rtn structure is referenced by the dp_f reep member of the datab 
structure. When f reeb(D3DK) is called to free the message, the driver's mes- 
sage freeing routine (referenced through the f ree_rtn structure) is called, with 
arguments, to free the data buffer. 

The f ree_rtn structure has the following declaration: 

struct free_rtn { 

void (*free_func) 0 / /* user's freeing routine */ 
char *free_arg; /* arguments to free_func() */ 

} 

typedef struct free_rtn frtn_t/ 

Instead of requiring a specific number of arguments, the free_arg field is 
defined of type char *. This way, the driver can pass a pointer to a structure if 
more than one argument is needed. 

NOTE: The f ree_func function must be defined in kernel space, should be 
declared void and accept one argument. It has no user context and must not 
sleep. 

RETURN VALUE 

On success, a pointer to the newly allocated message block is returned. On 
failure, NULL is returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

allocb(D3DK), freeb(D3DK), datab(D4DK), free_rtn(D4DK) 
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NAME 

esbbcall - call function when buffer is available 

SYNOPSIS 

tinclude <sys/stream.h> 

inblk_t *esbbcall(int pri, int func, long org); 
ARGUMENTS 

pri Priority of allocation request (to be used by allocb(D3DK) function, 

called by esbbcall) 

func Function to be called when buffer becomes available. 

org Argument to /unc. 

DESCRIPTION 

esbbcall, like bufcalKDSDK), serves as a tiineout(D3DK) call of indeter- 
minate length. If esballoc(D3DK) is unable to allocate a message and data 
block header to go with its externally supplied data buffer, esbbcall can be 
used to schedule the routine func, to be called with the argument org when a 
buffer becomes available, func may be a routine that calls esbbcall or it may 
be another kernel function. 

RETURN VALUE 

On success, 1 is returned. On failure, 0 is returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
allocb(D3DK), bufcall(D3DK), datab(D4DK), esballoc(D3DK) 
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NAME 

etoima jor - convert external to internal major device number 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/ddi.h> 

int etoima jor (majorat emaj) ; 

ARGUMENT 

emaj An external major number. 

DESCRIPTION 

etoima jor converts the external major number (emaj) to an internal major 
number. 

RETURN VALUE 

etoima jor returns the internal major number or NODEV if the external major 
number exceeds the bdevsw and cdevsw count. 

LEVEL 

Base or Interrupt 
SEE ALSO 

getemajor(D3D), geteminor(D3D), getmajor(D3DK), getminor(D3DK), 
itoemajor(D3D), makedevice(D3DK) 
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NAME 

f lushband - flush messages for a specified priority band 

SYNOPSIS 

finclude <sys/stream.h> 

void f lushband (queue_t q, unsigned char pri, int flag) ; 

ARGUMENTS 

q Pointer to the queue. 

pri Priority of messages to be flushed. 

flag Valid flag values are: 

FLUSHDATA Flush only data messages (types M_DATA, M_DELAY, 
MJPROTO, and M_PCPROtO). 

FLUSHALL Flush all messages. 

DESCRIPTION 

The f lushband fimction flushes messages associated with the priority band 
specified by pri. If pri is 0, only normal and high priority messages are flushed. 
Otherwise, messages are flushed from the band pri according to the value of flag. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
flushq(D3DK) 
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NAME 

f lushq - remove messages from a queue 

SYNOPSIS 

♦include <sys/stream.h> 

void f lushq (queue_t *q, int flag) ; 

ARGUMENTS 

*(i Pointer to the queue to be flushed. 

flag Valid flag values are: 

FLUSHDATA Flush only data messages (types M_DATA, M_DELAY, 
M_PROTO, and M_PCPROTO). 

FLUSHALL Rush all messages. 

DESCRIPTION 

flushq frees messages and their associated data structures by calling 
freexnsg(D3DK). If the queue's count falls below the low water mark and 
QWANtW is set, the nearest upstream service procedure is enabled. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
freemsg(D3DK), putq(D3DK) 
EXAMPLE 

This example depicts the canonical flushing code for STREAMS modules. The 
module has a write service procedure and potentially has messages on the queue. 
If it receives an M_FLUSH message, and if the FLUSHR bit is on in the first byte 
of the message (line 10), then the read queue is flushed (line 11). If the FLUSHW 
bit is on (line 12), then the write queue is flushed (line 13). Then the message is 
passed along to the next entity in the stream (line 14). See the example for 
qreply(D3PK) for the canonical flushing code for drivers. 



X /* 

2 * Module write-side put procedure. 

3 */ 

4 xxxwput(q, mp) 

5 queue__t *q; 

6 inblk_t *inp; 

7 { 

8 sfwitch(inp->b_datap->db_type) { 

9 case M_FLUSH: 

10 if (*mp->b_rptr & FLUSHR) 

11 f lushq (RD (q> , FLUSHALL) ; 

12 if (*inp->b__rptr & FLUSHW) 

13 f4.ushq(q, FLUSHALL); 

14 putnext (q, mp) ; 
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15 break; 

16 } 

17 } 
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NAME 

f reeb - free a message block 

SYNOPSIS 

♦include <sys/stream.h> 

void f reeb (inblk__t *bp) ; 
ARGUMENTS 

bp Pointer to the message block to be deallocated. inbl]c__t is an 

instance of the msgb(D4DK) structure. 

DESCRIPTION 

freeb deallocates a message block. If the reference count of the db_ref 
member of the datab(D4DK) structure is greater than 1, freeb decrements the 
count. If db_ref equals 1, it deallocates the message block and the correspond- 
ing data block and buffer. 

If the data buffer to be freed was allocated with the esballoc(D3DK) function, 
the buffer may be a non-STREAMS resource. In that case, the driver must be 
notified that the attached data buffer needs to be freed, and run its own freeing 
routine. To make this process independent of the driver used in the stream, 
freeb finds the free_rtn(D4DK) structure associated with the buffer. The 
free_rtn(D4DK) structure contains a pointer to the driver-dependent routine, 
which releases the buffer. Once this is accomplished, freeb releases the 
STREAMS resources associated with the buffer. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
allocb(D3DK), dupb(D3DK), esballoc(D3DK), free_rtn(D4DK) 
EXAMPLE 

See the copyb(D3DK) function page for an example of freeb. 
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NAME 

f reemsg - free all message blocks in a message 

SYNOPSIS 

tinclude <sys/stream.h> 

int f reemsg (inblk_t ; 
ARGUMENT 

mp Pointer to the message blocks to be deallocated. iriblk_t is an instance 

of the msgb(D4DK) structure. 

DESCRIPTION 

f reemsg calls f reeb(D3DK) to free all message and data blocks associated with 
the message pointed to by mp. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
f reeb(D3DK) 
EXAMPLE 

See the copymsg(D3DK) function page for an example of f reemsg. 
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NAME 

freerbuf - free a raw buffer header 

SYNOPSIS 

♦include <sys/buf .h> 
finclude <sys/ddi.h> 

void freerbuf (struct buf *bp) ; 
ARGUMENTS 

*bp Pointer to a previously allocated buffer header structure. 

DESCRIPTION 

freerbuf frees a raw buffer header previously allocated by getrbuf (D3DK). 
This function does not sleep and so may be called from an interrupt routine. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

getrbuf(D3DK), kmem__alloc(D3DK), kinem_free(D3DK), 
kmem zalloc(D3DK) 
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NAME 

getema jor - get external major device number 

SYNOPSIS 

♦include <sys /types. h> 
tinclude <sys/ddi.h> 

majorat getema jor (dev_t dev) ; 
ARGUMENT 

dev An external device number (contains both the major and minor 

number). 

DESCRIPTION 

getema jor returns the external major number given a device number, dev. 

RETURN VALUE 

The external major number. 

LEVEL 

Base or Interrupt 
SEE ALSO 

geteminor(D3D), etoimajor(D3DX getmajor(D3DK), makedevice(D3DK); 
getminor(D3DK) 
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NAME 

geteminor - get external minor device nxmiber 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/ddi.h> 

minor__t geteminor (dev_t dev) ; 

ARGUMENT 

dev External device number. 

DESCRIPTION 

geteminor returns the external minor number given a device number, dev. 

RETURN VALUE 

The external minor number. 

LEVEL 

Base or Interrupt 
SEE ALSO 

getemajor(D3D), etoima jor(D3D), getmajor(D3DK), makedevice(D3DK), 
getminor(D3DK) 
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NAME 

get error - return I/O error 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/buf.h> 

int geterror (struct buf *bp) ; 
ARGUMENT 

bp Pointer to the block interface buffer structure defined in buf . h. 

DESCRIPTION 

geterror is called to retrieve the error number from the error field of the buffer 
header structure. 

RETURN VALUE 

An error number indicating the error condition of the I/O request is returned. If 
the I/O requested is completed successfully, 0 is returned. 

LEVEL 

Base or Interrupt 

SEE ALSO 

buf(D4DK) 
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NAME 

getma jor ~ get major or internal major device number 

SYNOPSIS 

finclude <sys/types.h> 
finclude <sys/inkdev . h> 
♦include <sys/ddi.h> 

majorat getma j or (dev_t dev) ; 

ARGUMENT 

dev Device number. 

DESCRIPTION 

The getma jor function extracts either the major number or the internal major 
nimiber from a device number. For the 3B2, getma jor returns the internal 
major number. For architectures th^t do not make a distinction between internal 
and external major numbers, getma jor returns the major number. 

RETURN VALUE 

The major number or internal major number. 

NOTE: No validty checking is perifbrmed. If dev is invalid, an invalid number is 
returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guitie, Chapter 3, "Drivers in the UNIX Operating System" 
makedevice(D3DK), getminor(D3DK) 
EXAMPLE 

The following example shows both the getma jor and getminor(D3DK) func- 
tions used in a debug cmn__err(D3DK) statement to return the major and minor 
numbers for the device supported by the driver. This example is 3B2 specific. 

dev_t dev; 
#ifdef DEBUG 

cann_err(CE__NOTE, "Driver Started. Internal Major# = %d, 

Internal Minor# = %d'\ getma jor (dev) , getminor (dev) ) ; 
#endif 
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NAME 

getminor - get minor or internal minor device number 

SYNOPSIS 

♦include <sys/types.h> 

♦include <sys/mkdev.li> 

♦include <sys/ddi.h> 

minor_t getminor (dev_t dei?) ; 

ARGUMENT 

dev Device number. 

DESCRIPTION 

The getminor function extracts either the minor number or the internal minor 
number from a device number. For the 3B2, getminor returns the internal 
minor number. For architectures that do not make a distinction between internal 
and external minor numbers, getminor returns the minor number. 

RETURN VALUE 

The minor niuhber or interhal minor niimber, 

NOTE: No validty checking is performed. If dev is invalid, an invalid number is 
returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCl Driver Development Guide, Chapter 3, "Drivers in the UNIX Operating System" 
getroajor(D3DK), roakedevice(D3DK) 
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NAME 

getq - get the next message jfrom a queue 

SYNOPSIS 

tinclude <sys/streain.h> 

xiiblk^t *getq (queue^t *q) ; 
ARGUMENTS 

q Pointer to the queue from which the message is to be retrieved. 

DESCRIPTION 

getq is used by a service (srv(D2DK)) routine to retrieve its enqueued messages. 

A module or driver may include a service routine to process enqueued messages. 
Once the STREAMS scheduler calls srv it must process all enqueued messages, 
unless prevented by flow control, getq gets the next available message from 
the top of the queue pointed to by q. It should be called in a while loop that 
should be exited only when there are no more messages. 

getq turns the QWANTR flag off when a queue is being read, and turns QWANTR 
on when there are no more messages. When QWANTW is set it means an attempt 
has been made to write to the queue while it was blocked by flow control. If this 
is the case, getq back-enables (restarts) the service routine once it falls below the 
low water mark. 

RETURN VALUE 

If there is a message to retrieve, getq returns a pointer to it. If no message is 
queued, getq returns a NULL pointer. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 

STREAMS Programmer's Guide, Chapter 5, "Messages" 

bcanput(D3DK), canput(D3DK), putbq(D3DK), putq(D3DK), 
qenalDle(D3DK), srv(D2DK) 

EXAMPLE 

See the dupb(D3DK) function page for an example of getq. 
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NAME 

getrbuf - get a raw buffer header 

SYNOPSIS 

♦include <sys/buf .h> 
finclude <sys/kinem.h> 
♦include <sys/ddi.h> 

struct buf *getrbuf (long sUepflag) ; 

ARGUMENT 

sleepflag Indicates whether driver should sleep for free space. 
DESCRIPTION 

getrbuf allocates the space for a buffer header to the caller. It is used in cases 
where a block driver is performing raw (character interface) I/O and needs to set 
up a buffer header that is not associated with the buffer cache. 

getrbuf calls kxnein_alloc(D3DK) to perform the memory allocation, 
kmem alloc requires the information included in the sleepflag argument. If 
sleepjtag is set to KM_SLEEP, the driver may sleep until the space is freed up. If 
sleepflag is set to KM_NOSLEEP, the driver will not sleep. In either case, a pointer 
to the allocated space is returned or NULL to indicate that no space was available. 

RETURN VALUE 

A pointer to the allocated buffer header, or NULL if no space is available. 

LEVEL 

Base or Interrupt (must not sleep if calling from interrupt routine) 
SEE ALSO 

freerbuf(D3DK), kmein_alloc(D3DK), kmem free(D3DK) 
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NAME 



getvec - get an interrupt vector for a virtiial feature card address 



SYNOPSIS 



unsigned char getvec (long haddr) ; 



ARGUMENTS 

haddr 



A virtual feature card address. 



DESCRIPTION 



getvec returns an interrupt vector for a specified virtual feature card address, 
getvec is used in an init(D2D) routine. NOTE: If the feature card address is 
0, a divide-by-zero error can occur. 



Under all conditions, an unsigned char numeric value is returned. The only 
abnormal return value is a number not logical for the circumstances. 



With a 3B2 computer, each device that generates an interrupt must be given an 
interrupt vector location code. During system initialization, the driver in it rou- 
tine gets the interrupt vector location code (line 17) and stores the code in a 
predefined address on the interface card (an address on the card in the range of 
0x0 to 0x200000 can be defined to hold the code). 

When a device generates an interrupt, the interface card presents the code to the 
CPU, which uses it to locate the interrupt handling routine(s) of the driver. 



1 


struct device { 




/* 


physical device registers layout 


*/ 


2 


char 


reserve [4] ; 


/* 


reserve space on card 


*/ 


3 


ushort 


control; 


/* 


physical device control word 


*/ 


4 


char 


status; 


/* 


physical device status word 


*/ 


5 


char 


ivec_n\2in; 


/* 


device interrupt vector number in 


*/ 


6 






/* 


Oxf 0; subdevice reporting in OxOf 


*/ 


7 


paddr_t 


addr; 


/* 


address of data to be read/written 


*/ 


8 


int 


count; 


/* 


amount of data to be read/written 


*/ 


9 


); /* end device 


*/ 









10 



11 extern struct device *xx_addrl]; /* physical dev registers location */ 
12 

13 xx_init() 

14 { 

15 /* get device register struct */ 

16 register struct device *rp - xx_addr[0]; 

17 rp->ivec_num - getvec (xx_addr [ 0] ) ; /* get interrupt vector code */ 
18 

19 ) /* end xx_init */ 



RETURN VALUE 



LEVEL 



Base Only (Do not call from an interrupt routine) 



EXAMPLE 
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NAME 

hat_getkpf num - get page frame number for kernel address 

SYNOPSIS 

♦include <sys/vm.h> 
♦include <sys/types .h> 

u_int hat_getkpfnum(caddr_t addr) ; 
ARGUMENT 

addr The kernel virtual address for which the page frame number is to be 
returned. 

DESCRIPTION 

Drivers implementing the imnap(D2K) entry point must return -1 (for error) or 
the page frame number corresponding to the virtual address of the device 
memory addr. This frame nim\ber can be obtained by a call to hat__getkpf num. 

RETURN VALUE 

The page frame number corresponding to virtual address addr. There is no spe- 
cial error return value; invalid addresses will produce meaningless return values. 

LEVEL 

Base or interrupt. Although there is no reason why hat_getkpf num cannot be 
called at interrupt level, there is no need since it only needs to be called from 
iranap(D2K). 

SEE ALSO 

inroap(D2K), page_numtopp(D2DK), page_j>ptonuxn(D2DK) 
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NAME 



hdeeqd - initialize hard disk error logging 

SYNOPSIS 

♦include <sys/types . h> 
♦include <sy s/hdelog . h> 
♦include <sy s/xnkdev . h> 

int hdeeqd (o_dev_t dev, daddr_t j)dsno, short edtyj)) ; 
ARGUMENTS 

dev External device number (contains both the major number and the 



minor number). The driver must call the cmpdev macro (defined in 
mkdev . h) to compress the device number. 



EQD_EFC external floppy controller 

EQD__EHDC external hard disk controller 

EQD_ID integral disk drive 

EQD_IF integral floppy disk drive 

EQD_TAPE cartridge tape drive 



hdeeqd initializes information in the hard disk error logging table for the device 
specified by dev. This function is called once per device. 

NOTE: This function is not part of the default set of kernel functions. Ensure 
that the HDE bootable object module is placed in the /boot directory. 



Under all conditions, a 0 is returned. However, internal errors can occiir in 
hdeeqd causing a warning message to display on the console. Errors occur in 
the following conditions: 

The internal major device number is greater than or equal to the number of 
the controllers, called cdevcnt, which is assigned by Iboot when the 
operating system is loaded. The message is 

WARNING: hdeeqd: major (ddev) = int-major (>=cdevcnt) 

int-major is the internal major device number. 

The count of used disk slots in the error logging table exceeds the number 
of available slots. The message is 

WARNING: Too few HDE equipped slots 

bad block handling skipped for maj/min = ext-maj, ext-min 

ext-maj and ext-min are the external major and minor numbers. 



pdsno 
edtyp 



Physical description sector 

Error device type. The valid values are 



DESCRIPTION 



RETURN VALUE 



LEVEL 



Base or Interrupt 
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SEE ALSO 

BCI Driver Development Guide, Chapter 12, "Error Reporting" 
hdelog(D3D), hdedata(D4D) 
EXAMPLE 

When a device is opened for the first time, the driver open(D2DK) or 
init(D2D) routines (open in this example) must identify the device and set up 
controlling information about the device. In this example, the information is kept 
on a controlling sector on the disk. If the controlling sector does not exist, the 
information is encoded as a static table in the driver. 



1 


♦define XX_CNTLBLKNO 0 /* 


controlling sector block number 


*/ 


2 


Struct device { /* 


physical device registers layout 


*/ 


3 


char reserve [4]; /* 


reserve space on card 


*/ 


4 


ushort control; /* 


physical device control word 


^/ 


5 


char status; /* 


physical device status word 


*/ 


6 


char lvec__nuin; /* 


device interrupt vector number in 


*/ 


7 


/* 


OxfO; subdevice reporting in OxOf 


*/ 


8 


paddr_t addr; /* 


data address to be read/written 


*/ 


9 


int count; /* 


amount of data to be read/written 




10 


}; /* end device */ 






11 


struct xx_ { 


/♦logical device structure 


*/ 


12 


struct buf *xx_head; 


/* I/O buffer queue head pointer 


*/ 


13 


struct buf *xx__tail; 


/* I/O buffer queue tail pointer 


*/ 


14 


short xx_flag; 


/* logical status flag 


*/ 


15 


struct hdedata xx__edata; 


/* disk error log error record 


*/ 


16 


struct iostat xx__stat; 


/* unit I/O statistics for 


*/ 


17 


/* establishing 


an error rate during error logging 


*/ 


18 


}; /* end xx_ */ 






19 








20 


struct xx__inf o { 


/* information on control sector 


*/ 


21 


long xx_id; 


/* disk device id code 


*/ 


22 


long xx_cyl; 


/* total number of cylinders 


*/ 


23 


long xx_trk; 


/* number of tracks per cylinder 


*/ 


24 


long xx__sec; 


/* number of sectors per track 


*/ 


25 


char xx_serial [ 12 ] ; 


/* device serial number 


*/ 


26 


}; /* end xx_info */ 






27 








28 


extern struct xx__ xx_devtab[]; 


/* logical device structures table 


*/ 


29 


extern struct device *xx__addr[]; 


/* physical dev registers location 


*/ 


30 


extern struct xx_info xx_info(]; 


/* device control information 


*/ 


31 


extern int xx_cnt; 


/* number of devices 


*/ 


32 


xx_open(dev, flag, otyp, crp) 






33 


dev__t *dev; 






34 


int flag, otype; 






35 


struct cred *crp; 






36 


{ 






37 


register struct xx__ *dp; 






38 


register struct device *rp; 
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39» register Int unit; 

40 unit - getmlnor (dev) » 4; /* get drive unit number */ 

41 dp - &xx_jdevtab(unit]; /* get logical device information */ 

42 if ( (dp->xx_f lag 4 XX__OPEN) — 0) { /* if first time device opened */ 

43 register struct buf *bp; 

44 hdeeqd(cnipdev(dev), XX__CNTLBLKNO, EQD_ID> ; /* initialize errbr logging */ 

45 bp - kmero_alloc(1024, KM__NOSLEEP) ; /* get control sector buffer */ 

46 bp->b_flags - B_READ; /* set up buffer to read */ 

47 bp->b_blkno - XX_CNTLBLKNO; /* control sector from disk */ 

48 bp->b_count - 512; 

49 bp->b_dev - dev; 

50 xx_strategy(bp) ; /* read control sector */ 

51 biowait(bp); /* wait for read to complete */ 

52 i^ ( (bp->b_f lags & B_ERROR> !- 0 > { 

53 /* if data error occurred, display message on console */ 

54 3tx_print (dev, "xx^open: cannot read control sector") ; 

55 ) else { /* copy control sector data to info table */ 

56 bcopy(bp->b_un.b__addr, &xx__inf o[unit] , sizeof (struct xx_info)); 

57 hdeeqd(cmpdev(dev) , XX_CNTLBLKNO, EQD_ID); /* start error logging */ 

58 dp->flag |- XX_pPEN; /* indicate device open */ 

59 } /* endif */ 

60 brelse(bp); /* release system buffer */ 

61 ) /* endif */ 



If this is the first open, hdeeqd (line 44) is used to initiate error logging for the 
device. A system buffer is allocated (line 45) and the driver reads the controlling 
sector from the xx_strategy routine (line 50). If an error occurred on the read 
attempt, an error message is displayed (line 54) and an error condition is 
returned. Otherwise, the driver saves information from the controlling sector 
with bcopy (line 56) and indicates the device has been opened. Finally, the sys- 
tem buffer is released (line 60). 
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NAME 

hdelog - log hard disk error 

SYNOPSIS 

♦include <sys /types .h> 
♦include <sys/hdelog.h> 
♦include <sys/mkdev . h> 

int hdelog (struct hdedata *eptr) ; 

ARGUMENT 

eptr Pointer to the hdedata(D4D) structure defined in sys/hdelog.h. 

The driver developer places information in the structure before hde- 
log is called. 

DESCRIPTION 

hdelog logs a hard disk error in the error logging queue and displays a warning 
message on the console to alert the operator to the problem. 

The console message is 

WARNING: severity readtype hard disk error: 
maj /min ^ extemal-major-num, extemaUminor-num 

where severity \s "marginal" or "unreadable", eind readiype is "CRC" (cyclic 
redimdancy check) or "ECC" (error check and correction). 

hdeeqd(D3D) must be called once before this function to initialize error logging, 
hdelog logs disk drive media errors. NOTE: This function is not part of the 
default kernel. Ensure that the HDE bootable object module is placed in the 
/boot directory. 

Before calling this function, values must be assigned to the hdedata(D4D) struc- 
ture. These members include the device number; the disk pack serial number; the 
physical block address; the type of read operation CRC or ECC; whether the error 
is marginal or whether the disk is imreadable; the number of unreadable tries; the 
bit width of the corrected error; and a time stamp. 

RETURN VALUE 

Under all conditions, a 0 is returned. However, an internal error can occur in 
hdelog causing a warning message to display on the console. This error occurs 
when the error logging table is full. In this case, the usual disk error warning 
message is prefaced with 

WARNING: HDE queue full, following report not logged 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Dni7er Dei;e/opm^i Gui^fe, Chapter 12, "Ermr Reporting" 
hdeeqd(D3D), hdedata(D4D) 
EXAMPLE 

A driver interrupt routine must check for data transfer errors (called data checks). 
When a data check occurs (reported by the device in the status or error register), 
the driver determines if there have been sufficient attempts to resolve the error. 
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If so, the driver abandons the I/O request by marking the buffer as being in 
error, logging an unresolved error (line 60), and marking the I/O operation com- 
plete (line 61). When an error persists in spite of multiple attempts to resolve it, 
the driver logs marginal errors (line 75) and attempts the I/O operation again. 
The driver may try to resolve the error with software by using the error correc- 
tion bits in an error check and correction (ECC) register. See hdedata(D4D) for 
a description of the xx_edata structure shown in this example line 17). 



1 


struct device ( 










2 






/* 


layout of physical device regs 


*/ 


3 


char 


reserve [4] ; 


/* 


reserve space on card 


*/ 


4 


ushort 


control; 


/* 


physical device control word 


*/ 


5 


char 


status; 


/* 


physical device status word 


*/ 


6 


char 


ivec__num; 


/* 


device interrupt vector no. in 


*/ 


7 






/* 


OxfO; subdevice in OxOf 


*/ 


8 


paddr__t 


addr; 


/* 


address of data read/written 


*/ 


9 


int 


count; 


/* 


amount of data read/written 


*/ 


10 


}; /* end device 


*/ 








11 












12 


struct xx_ { 










13 






/* 


logical device structure 


*/ 


14 


struct buf 


*xx_head; 


/* 


I/O buffer queue head pointer 


*/ 


15 


struct buf 


*xx_tail; 


/* 


I/O buffer queue tail pointer 


*/ 


16 


short 


xx_f lag; 


/* 


logical status flag 


*/ 


17 


struct hdedata xx__edata; 


/* 


hard disk error record 


*/ 


18 


struct iostat xx_stat; 


/* 


unit I/O stats for setting an 


*/ 


19 






/* error rate during error logging 


*/ 


20 


}; /* end xx_ */ 










21 












22 


struct xx_info { 










23 




/* 


information on disk control sector 


*/ 


24 


long xx_ 


.id; 


/* 


device id code 


*/ 


25 


long xx_ 


_cyl; 


/* 


total number of cylinders 


*/ 


26 


long xx_ 


_trlc; 


/* 


number of tracks per cylinder 


*/ 


27 


long xx_ 


_sec; 


/* 


number of sectors per track 


*/ 


28 


char xx_ 


.serial [12] ; 


/* 


device serial number 


*/ 


29 


}; /* end xx_info 


*/ 








30 


extern struct xx_ 


xx__devtab [ 


];/* 


logical dev structures table 


*/ 


31 


extern struct device *xx__addr[]; 


/* 


physical dev register location 


*/ 


32 


extern struct xx__info xx__infoI]; 


/* 


device control information 


*/ 


33 


extern int 


xx_cnt; 


/* 


number of devices 


*/ 


34 


xx__int (board) 










35 


int board; 








36 


{ 






/* get dev registers 


*/ 


37 


register struct device *rp - 


xx_addr [board] ; 




38 


register struct 


xx_ *dp; 








39 


register struct 


buf *bp; 








40 
41 


register int 


unit; 








42 


unit - (board « 4) | (rp->ivec_nuin & Oxf > ; /* make unit number 


*/ 
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43 dp - 4xx_devtab [unit] ; 

44 if ((rp->status & DATACHK) !- 0) { 

45 /* if data check error occurred */ 

46 if (++dp->xx_edata.badrtcnt > XX_MAXTRY> { /* if sufficient */ 

47 /* attempts have been made/ then abandon the I/O request */ 

48 bp - dp->xx_head; /* get buffer from I/O queue */ 

49 dp->xx_head - bp->av__forw; /* remove buffer from I/O queue */ 

50 bp->b_flags I- B_ERROR; /* mark buffer as being in error */ 

51 bp->b_error - EIO; /* supply error condition */ 

52 /* supply information needed for error logging */ 

53 dp->xx_edata.diskdev - cmpdev (bp->b__dev) ; /* device number */ 

54 dp->xx_edata.blkaddr - bp->b__blkno; /* block no. in error */ 

55 dp->xx__edata.readtype - HDEECC; /* error type: error check */ 

56 dp->xx_edat a. severity - HDEUNRD; /* data was unreadable */ 

57 dp->xx_edata.bitwidth - 0; 

58 dp->xx_edata.timestmp - time; /* time recording occurred */ 

59 bcopy (dp->xx_edata.dskserno, xx_info [unit] .serial, 12); 

60 hdelog(&dp->xx_edata) ; /* log abandoned I/O operations*/ 

61 biodone(bp); /* mark I/O operation complete */ 
62 

63 ) else if (dp->xx__edata . badrtcnt > 1) {/* if more than one retry */ 

64 /* log error as marginal */ 

65 bp - dp->xx__head; /* get buffer from I/O queue but leave on */ 

66 /* I/O queue so that I/O operation is repeated */ 

67 /* supply information needed for error logging */ 

68 dp->xx_edata.diskdev » cmpdev(bp->b_dev) ; /* device number */ 

69 dp->xx_j6data.blkaddr - bp~>b_blkno; /* error block number */ 

70 dp->xx_edata . readtype « HDEECC; /* err. type: error check */ 

71 dp->xx_edata . severity - HDEMARG; /* marginal error */ 

72 dp->xx_edata.bitwidth - 0; 

73 dp->xx__edata . t imes tmp - time; /* time recording occurred */ 

74 bcopy (dp->xx_edata .dsksemo, xx_info [unit] .serial, 12) ; 

75 hdelog(fidp->xx_jedata) ; /* log data check error */ 

76 } /* endif */ 

77 ) /* endif */ 



78 } 
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NAME 

insq - insert a message into a queue 

SYNOPSIS 

♦include <sys/stream.h> 



insq(D3DK) 



int insq (queue_t itiblk^t *emp, xnblk_t *ninp) ; 
ARGUMENTS 

q Pointer to the queue containing message emp. 

emp Enqueued message before which the new message is to be inserted 
(xnblk^t is an instance of the ms9b(D4DK) structure). 

nmp Message to be inserted. 

DESCRIPTION 

insq inserts a message into a queue. The message to be inserted, nmp, is placed 
in q immediately before the message emp. If emp is NULL, the new message is 
placed at the end of the queue. The queue class of the new message is ignored. 
All flow control parameters are updated. The service procedure is enabled unless 
QNOENB is set. 

CAUTION: If emp is non-NULL, it must point to a message on or a system panic 
could result. 

RETURN VALUE 

insq returns 1 on success, and 0 on failure. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCl Driver Development Guide, Chapter 7, "STREAMS" 
EXAMPLE 

This routine illustrates the steps a transport provider may take to place expedited 
data ahead of normal data on a queue (assume all M_DATA messages are con- 
verted into M_PROTO T_DATA_REQ messages). Normal T_DATA__REQ messages 
are just placed on the end of the queue (line 14). However, expedited 
T_EXDATA_REQ messages are inserted before any normal messages already on the 
queue (line 28). If there are no normal messages on the queue, bp will be NULL 
and we will fall out of the for loop (line 21). insq will act like putq(D3DK) 
in this case. 

1 ilnclude <sys/tlhdr.h> 
2 

3 xxxwput(q, mp) 

4 qaeue__t *q; 

5 inblk_t *inp; 

6 { 

7 union T^primitives *tp; 
8 

9 switch (mp->b__datap-->db_type) { 

10 case M__PROTO: 

11 tp - (union T_priinitives *)inp->b_rptr; 
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12 switch (tp->type> { 

13 case T__DATA__REQ : 

14 putq(q, mp); 

15 break; 
16 

17 case T_EXDATA_REQ : 

19 mblJc^t *bp; 

20 union T__priinitives *ntp; 
21 

22 for (bp - q->q__first; bp; bp « bp->b_next) { 

23 if (bp->b__datap->db_type M_PROTO) { 

24 ntp - (union T__priinitives *)bp->b__rptr; 

25 if (ntp->type !- TJEXDATA__REQ) 

26 break; 

27 } 

28 } 

29 insq(q, bp, mp) ; 

30 break; 

32 } 



33 } 

34 } 
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NAME 

itoema jor - convert internal to external major device number 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/ddi.h> 

int itoema jor (majorat imaj, int preventaj) ; 

ARGUMENTS 

imaj An internal major number. 

prevermj Most recently obtained external major number (or NODEV, if this is the 
first time the function has been called). 

DESCRIPTION 

itoeroajor converts the internal major number to the external major number. 
The external-to-intemal major number mapping is many-to-one, and so any inter- 
nal major number may correspond to more than one external major number. By 
repeatedly invoking this fimction and passing the most recent external major 
number obtained, the driver can obtain all possible external major number values. 

RETURN VALUE 

External major number, or NODEV, if all have been searched 

LEVEL 

Base or Interrupt 
SEE ALSO 

geteinajor(D3D), geteminor(D3D), etoiina jor(D3D), getma jor(D3DK), 
getminor(D3DK), inakedevice(D3DK) 
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NAME 

kinem_alloc - allocate space from kernel free memory 

SYNOPSIS 

♦include <sys/types .h> 
tinclude <sys/)cxnein.h> 

_VOID *k2nem_ alloc (size_t size, int flag) ; 

ARGUMENTS 

size Niimber of bytes to allocate. 

flag Determines if caller wttl sleep to wait for free space. Possible flags are 

IM^SLEEP to sleep while waiting for free space, and KM_NOSLEEP to 
return NULL if space is not available. 

DESCRIPTION 

The kmem_alloc fimction allocates a specified amoimt of kernel memory in 
bytes and returns a pointer to the allocated memory. The flag argument deter- 
mines whether the function will sleep while waiting for free space to be released. 
If flag has KM_SLEEP set, the caller may sleep until free space is available. If flag 
has KM_NOSLEEP set and space is not available, NULL will be returned. 

NOTE: Memory allocated by kinein__alioc is not paged. Available memory is 
therefore limited. Excessive use of this memory is likely to affect overall system 
performance. 

RETURN VALUE 

If successfull, kmem^alloc returns a pointer to the allocated space. NULL is 
returned if KMTNOSLEEP is set and memory cannot be allocated. 

LEVEL 

Base (interrupt only if KM_NOSLEEP is set in flag) 
SEE ALSO 

freerbuf(D3DK), getrbuf(D3DK), kinem_free(D3DK), 
kmem_zalloc(D3DK), rinalloc(D3DK), nnfree(D3DK), rminit(D3DK), 
rmsetwant(D3DK), rmwant(D3DK) 
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NAME 

kmem_f ree - free previously allocated kernel memory 

SYNOPSIS 

♦include <sys/tpes.h> 
♦include <sys/kmem.h> 

void kraem^f ree (_VOID *cp, size_t size) ; 
ARGUMENTS 

q) Address of the allocated storage from which to return size of allocated 

memory. 

size Nimiber of bytes to free (same number of bytes as allocated by 

kroem_alloc(D3DK) or kxnem_zalloc(D3DK). 

DESCRIPTION 

This fimction returns size of storage to kernel free space previously allocated by 
kxnem_alloc(D3DK) or kmem_zalloc(D3DK). The cp and size values must 
specify exactly one complete area of allocated memory. One kmexn^free call 
must correspond to one allocation. 

RETURN VALUE 

Under all conditions/no value is returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

freerbuf(D3DK), getrbuf(D3DK), kinem_alloc(D3DK), 
kmem_zalloc(D3DK), rnialloc(D3DK), rmfree(D3DK), rminit(D3DK), 
rmsetwant(D3PK), rmwant(D3DK) 
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NAME 

kmem_zalloc - allocate and clear space from kernel free memory 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/kinem.h> 

_V0ID*kmein_2alloc (unsigned long sizg, unsigned long flag); 

ARGUMENTS 

size Nimiber of bytes to allocate. 

flag Determines if caller may sleep to wait for free space. Possible flags are 

KM_SLEEP to sleep while waiting for free space, and KM__NOSLEEP to 
return NULL if space is not available. 

DESCRIPTION 

This fimction allocates size of storage from kernel free space, clears it, and returns 
a pointer to the allocated memory. If flag has KM_SLEEP set, the caller may sleep 
until free space is available. If flag has KM_NOSLEEP set and space is riot avail- 
able, NULL will be returned. 

NOTE: Memory allocated by kmem^zalloc is not paged. Available memory is 
therefore limit^. Excessive use of this memory is likely to affect overall system 
performance. 

RETURN VALUE 

kinem_zalloc returns NULL if memory cannot be allocated. Otherwise, it 
returnjs a pointer to the allocated space. 

LEVEL 

Base (interrupt only if KM_NOSLEEP is set in ^ag) 
SEE ALSO 

freerbuf(D3DK), getrbuf(D3DK), kinem_alloc(D3DK), kinein_free(D3DK), 
rinalloc(D3DK), rmf ree(D3DK), rminit(D3DK), rxnsetwant(D3DK), 
rmwant(D3DK) 
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NAME 

kvtophys - convert kernel virtual address to physical address 

SYNOPSIS 

♦include <sys/types.h> 
finclude <sys/ddi.h> 

paddr_t kvtophys (caddr_t caddr) ; 

ARGUMENTS 

caddr Kernel virtual address to translate. 

DESCRIPTION 

This function returns the physical address equivalent of the specified kernel vir- 
tual address. The same functionality is provided in the vtop(D3D) function. 

RETURN VALUE 

kvtophys returns NULL if caddr is invalid; otherwise, a physical address is 
returned. CAUTION: If caddr is invalid, kvtophys could panic the system. 

LEVEL 

Base or Interrupt 

SEE ALSO 

vtop(D3D) 



3-82 



10/89 



linkb(D3DK) 



linkb(D3DK} 



NAME 

linkb - concatenate two message blocks 

SYNOPSIS 

♦include <sys/stream.h> 

void linkb (inblk_t * mpl, mblk^t *mp2) ; 
ARGUMENTS 

mpl The message to which mpl is to be added, mblk^t is an instance of 
the msgb(D4DK) structure. 

mp2 The message to be added. 

DESCRIPTION 

linkb creates a new message by adding mp2 to the tail of mpl. The continuation 
pointer (b_cont) of the first message is set to point to the second message: 



mpl 



b__datap 
b cont 



mp2 



db base 



data 
buffer 



b_datap 
b cont (0) 



db base 



data 
buffer 



linkb (mpl, mp2); 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
unlinkb(D3DK) 
EXAMPLE 

See the dupb(D3DK) function page for an example of linkb. 
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NAME 

inakedevice - make device number from external major and minor 

SYNOPSIS 

♦include <sys/types.h> 
♦include <sys/inakedev.h> 
♦include <sys/ddi.h> 

dev_t inakedevice (majorat majnum, minor_t tninnum) ; 

ARGUMENTS 

majnum External major number. 

minnum External minor number. 
DESCRIPTION 

The inakedevice fimction creates a device number from an external major and 
external minor device nimiber. xnakdevice should be used to create device 
numbers so that additional overhead on the driver can be avoided, and so the 
driver will port easily to releases that treat device numbers differently. 

RETURN VALUE 

The device ntimber, containing both the major number and the minor number, is 
returned. No validation of the external major or minor numbers is performed. 

NOTE: The nimibers returned by getmajor(D3DK) and getminor(D3DK) are 
not valid arguments to inakedevice in systems where there is a distinction 
between internal and external numbers. The ftmctions geteinajor(D3D) and 
geteininor(D3D) should be used on those systems. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 3, 'T)rivers in the UNIX Operating System" 
geteinajor(D3D), geteininor(D3D), getinajor(D3DK), getminor(D3DK) 
EXAMPLE 

In the following example inakedevice creates device numbers for every device 
supported by the example init(D2D) routine. The init routine initializes each 
device by calling the xxx__dev_init () routine (line 8) with the device number 
for each device. The device numbers are created from the preconfigured major 
device number, XXMAJOR, and the range of valid minor numbers for the device. 

1 xxxinitO 

2 { 



3 dev_t dev; 

4 ininor_t min; 
5 

6 for (mln - 0; mln < XXMAXMIN; mln++) { 

7 dev "* makedevlce (XXMAJOR, mln) ; 

8 xxx__dey_lnit (dev) ; 

9 } 



10 ) 
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NAME 

max - return the larger of two integers 

SYNOPSIS 

int max(int intl, int intZ) ; 

ARGUMENTS 

intl, intl The integers to be compared. 

DESCRIPTION 

max compares two integers and returns the larger of two. 

RETURN VALUE 

The larger of the two numbers. 

LEVEL 

Base or Interrupt 

SEE ALSO 

min(D3DK) 
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NAME 

min - return the lesser of two integers 

SYNOPSIS 

int min(int intl, int inti) ; 

ARGUMENTS 

intl, intl The integers to be compared. 

DESCRIPTION 

min compares two integers and returns the lesser of the two. 

RETURN VALUE 

The lesser of the two integers. 

LEVEL 

Base or Interrupt 

SEE ALSO 

inax(D3DK) 
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NAME 

msgdsize - return the number of bytes in a message 

SYNOPSIS 

♦include <sys/stream.h> 

int msgdsize (inblk_t *mp) ; 

ARGUMENT 

mp Message to be evaluated. 

DESCRIPTION 

msgdsize counts the number of bytes in a data ijiessage. Only bytes included in 
the data blocks of type M__DATA are included in the count. 

RETURN VALUE 

The number of data bytes in a message, expressed as an integer. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
EXAMPLE 

See the bufcall(D3DK) function page for an example of the msgdsize fimc- 
tion. 
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NAME 

noenable - prevent a queue from being scheduled 

SYNOPSIS 

♦include <sys/stream.h> 
♦include <sys/ddi.h> 

void noenable (queue__t ""q) ; 

ARGUMENT 

q Pointer to the queue. 

DESCRIPTION 

The noenable function prevents the queue q from being scheduled for service 
by insq(D3DKX or by putq(D3DK) or putbq(D3DK) when enqueuing an ordi- 
nary priority message. The queue can be re^nabled with the enableok(D3DK) 
function. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 

enableok(D3DK), insq(D3DK), putq(D3DK), putbq(D3DK), 
qenable(D3DK) 
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NAME 

OTHERQ - get pointer to queue's partner queue 

SYNOPSIS 

♦include <sys/stream.h> 
♦include <sys/ddi.h> 

queue__t *OtiffiRQ (queue_t ; 

ARGUMENT 

q Pointer to the queue. 

DESCRIPTION 

The OTHERQ function returns a pointer to the other of the two queue structures 
that make up a STREAMS module or driver. If q points to the read queue the 
write queue will be returned, and vice versa. 

RETURN VALUE 

OTHERQ returns a pointer to a queue's partner. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCl Driver Devebpment Guide, Chapter 7, "STREAMS" 
EXAMPLE 

This routine sets the minimum packet size, the maximum packet size, the high 
water mark, and the low water mark for the read and write queues of a given 
module or driver. It is passed either one of the queues. This could be used if a 
module or driver wished to update its queue parameters dynamically. 



1 


void 


2 


set__CLj>arains (q, min, max, hi, 


3 


queue__t *q; 


4 


dhort mln; 


5 


short max; 


6 


u short hi; 


7 


u short lo; 


8 


{ 


9 


q->CLJ'™inpsz - min; 


10 


q->q_maxpsz - max; 


11 


q->CLhiwat - hi; 


12 


q->q_lowat » lo; 


13 


OTHERQ (q)->q_minpsz - min; 


14 


OTHERQ (q)~>qjmaxpsz - max; 


15 


OTHERQ (q) ->q__hiwat - hi; 


16 


OTHERQ (q) ->q_lowat - lo; 


17 


} 
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NAME 

pagejiumtopp - convert page frame number to page structure 

SYNOPSIS 

♦include <sys/types.h> 
♦include <vm/page.h> 

page_t page__numtopp(u_int pfn) ; 
ARGUMENT 

pfn The page frame number to be converted. 

DESCRIPTION 

page__n\imtopp converts a page frame number to its corresponding page struc- 
ture. 

RETURN VALUE 

A pointer to the page structure is returned. If the page frame number is invalid, 
NULL is returned. 

LEVEL 

Base or Interrupt 

SEE ALSO 

page_pptonum(D3DK) 
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NAME 

page_pptonum - convert page structure to page frame number 

SYNOPSIS 

♦include <sys/types .h> 
♦include <vm/page.h> 

u_int page_pptonuin(page_t *pp) ; 

ARGUMENT 

pp Pointer to a page structure. 

DESCRIPTION 

pagejpptonum is called to convert a page structure to its corresponding page 
frame ntimber. 

RETURN VALUE 

The page frame number corresponding to the page structure is returned. No 
error is returned. If pp (the page structure address) is invalid, the system will 
panic. 

LEVEL 

Base or Interrupt 

SEE ALSO, 

page_numtopp(D3DK), 
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NAME 

physiock - validate and issue raw I/O request 

SYNOPSIS 

#include<sys /types .h> 
♦include <sys/buf .h> 
♦include <sys/errno . h> 
♦include <sys/uio.h> 
♦include <sys/cred.h> 

int physiock (int {* (strategy) {) , struct buf *buf,devJodev, 
int rwflag, daddr_t nblocks, uio_t *uioj)) ; 

ARGUMENTS 

strategy Address of the driver strategy routine. 

buf Pointer to the buf structure describing the I/O request. If set to 

NULL, then a buffer is allocated from the buffer pool and returned to 
the free list after the transfer completes. 

dev Device number. 

rwflag Flag indicating whether the access is a read (B_READ) or a write 
(B__WRITE). Note that BJWRITE cannot be directly tested as it is 0 

nblocks Ntimber of blocks that a logical device can support, for example, a 
disk partition, or tape. 

uio_p Pointer to the uio structure that defines the user space of the I/O 
request. 

DESCRIPTION 

physiock is called by the character interface to block driver read(D2DK) and 
write(D2DK) routines to help perform unbuffered I/O while maintaining the 
buffer header as the interface structure. 

physiock performs the following functions: 

verifies the requested transfer is valid by checking if the offset is at or past 
the end of the device 

sets up a buffer header describing the transfer 

faults pages in and locks the pages impacted by the I/O transfer so they 
can not be swapped out 

calls the driver strategy(D2DK) routine passed to it 

sleeps until the transfer is complete and is awakened by the 
biodone(D3DK) function in the driver's interrupt routine 

performs the necessary cleanup and updates, then returns to the driver 
routine 

A transfer using physiock is considered valid if the specified data location 
exists on the device, and the user has specified a storage area that exists in user 
memory space. 
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RETURN VALUE 

physiock returns 0 if the result is successful, the appropriate error number upon 
failure, physiock returns the ENXIO error (see Appendix A for more informa- 
tion) if an attempt is made to read beyond the end of the device. If a read is per- 
formed at the end of the device, 0 is returned. ENXIO is also returned if an 
attempt is made to write at the end of a device or beyond the end of the device. 
EFAULT is returned if user memory is not available. EAGAIN is returned if phy- 
siock could not lock pages for DMA. 

LEVEL 

Base Only (Do not call from an interrupt routine) 

SEE ALSO 

dina__pageio(D3D), strategy(D2DK) 

EXAMPLE 

1 struct dslze { 

2 daddr__t nblocks; /* disk partition block number */ 

3 int cyloff; /* starting cylinder # of partition */ 

4 } DISKsi2es[163 - { 
5 



6 


20448, 


21, 


/* 


partition 


0 




cyl 


21-305 


*/ 


7 


12888, 


126, 


/* 




1 




cyl 


126-305 


*/ 


8 


9360, 


175, 


/* 




2 




cyl 


175-305 


*/ 


9 


7200, 


205, 


/* 




3 




cyl 


205-305 


*/ 


10 


3600, 


255, 


/* 




4 




cyl 


255-305 


*/ 


11 


21816, 


3, 


/* 


ff 


5 




cyl 


2-305 


*/ 


12 


21888, 


1, 


/* 


tt 


6 




cyl 


1-305 


*/ 


13 


72, 


1, 


/* 


tf 


7 




cyl 


1 


*/ 



14 }; 
15 

16 DISKread(dev, uio_j), cred_p) /* direct read request from block device */ 

17 dev_t dev; 

18 uio_t *uio__p; 

19 credit *cred_p; 

20 ( 

21 register int nblks; 
22 

23 /* get number of blocks in the partition */ 

24 nblks - DISKsizes [minor (dev) & 0x7] .nblocks; 
25 

26 /* 

27 * Check limits of read request. If request is in 

28 * the limits of the disk partition, schedule direct I/O. 

29 */ 
30 

31 physiock(DISKstrat, 0, dev, B__READ, nblks, uio__p) ; 

32 

33 } /* end DISKread */ 

34 

35 
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36 DISKwrlte (dev, uio_j), cred_p) /* direct write request to block device */ 



36 dev_t dev; 

37 ulo_t *uio__p; 

38 cred__t *credjp 

39 { 

40 register Int nblks; 
41 

42 /* get number of blocks In the partition */ 

43 nblks ~DISKslzes[ minor (dev) £ 0x7] .nblocks; 
44 

45 /* 

46 * Check limits of write request. If request is in 

47 * the limits of the disk partition, schedule direct I/O. 

48 */ 
49 

50 phy s lock (DISKst rat, 0, dev, B_f9RITE, nblks, ulo_j>) ; 
51 



52 ) /* end DISKwrlte */ 
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NAME 

pollwakeup - inform a process that an event has occurred 

SYNOPSIS 

♦include <sys/poll.h> 

void pollwakeup (struct pollhead *php, short event) ; 

ARGUMENTS 

pkp Pointer to a pollhead structure. 

event Event to notify the process about. 
DESCRIPTION 

The pollwakeup function wakes a process waiting on the occurrence of an 
event. It should be called from a driver for each occurrence of an event. The 
pollhead structure will usually be associated with the driver's private data 
structure associated with the particular minor device where the event has 
occurred. See chpoll(D2DK) and poll(2) for more detail. 

RETURN 

None 

LEVEL 

Base or Interrupt 

SEE ALSO 

chpoll(D2DK), poll(2) 
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NAME 

ptob ~ convert size in pages to size in bytes 

SYNOPSIS 

♦include <sys/ddi.h> 

unsigned long ptob (unsigned long numpages) ; 
ARGUMENT 

numpages Size in number of pages to convert to size in bytes. 
DESCRIPTION 

This function returns the number of bytes that are contained in the specified 
ntimber of pages. For example, if the page size is 2048, then ptob (2) returns 
4096. ptob(O) returns 0. 

RETURN VALUE 

The rettirn value is always the number of bytes in the specified number of pages. 
There are no invalid input values, and no checking will be performed for 
overflow in the case of a page count whose corresponding byte count cannot be 
represented by an unsigned long. Rather, the higher order bits will be 
ignored. 

LEVEL 

Base or interrupt 

SEE ALSO 

btop(D3DK), btopr(D3DK) 
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NAME 

pullupmsg - concatenate bytes in a message 

SYNOPSIS 

♦include <sys/stream.h> 

int pullupmsg (xnblk_t *mp, int kn) ; 
ARGUMENTS 

*mp Pointer to the message whose blocks are to be concatenated. xnblk_t 
is an instance of the msgb(D4DK) structure. 

len Number of b)^es to concatenate. 

DESCRIPTION 

Jpullupmsg tries to combine multiple data blocks into a single block, pul- 
lupmsg concatenates and aligns the first len data bytes of the message pointed to 
by mp. If len equals -1, all data is concatenated. If len bytes of the same mes- 
sage type cannot be found, pullupmsg falls and returns 0. 

RETURN VALUE 

On success, 1 is returned; on failure, 0 is returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
allocb(D3DK) 
EXAMPLE 

This is a driver write srv(D2DK) (service) routine for a device that does not sup- 
port scatter/gather DMA. For all M_DATA messages, the data will be transferred 
to the device with DMA. 

First, try to pull up the message into one message block with the pullupmsg 
function (line 12). If successful, the transfer can be accomplished in one DMA job. 
Otherwise, it must be done one message block at a time (lines 19-22). After the 
data has been transferred to the device, free th^ message and continue processing 
messages on the queue. 

1 xxxwsrv(q) 



2 queue_t *q; 

3 { 

4 inblk__t *rop; 

5 inblk__t *tmp; 

6 caddr__t dma_addr; 

7 int dma^len; 
8 

9 yfhilo ((mp - getq(q)) !- NULL) { 

10 switch (inp->b_datap->db_type> { 

11 case M_nATA: 

12 (pullupmsg (mp, -1>) { 

13 dma__addr - vtop (mp->b_rptr> ; 

14 dma__len - mp^>b__wptr - mp->b__rptr; 
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15 xxx__do_jclina (dina__addr, dma^len) ; 

16 freeinsg(inp) ; 

17 break; 

18 ) 

19 for (tmp - mp; tmp; tmp - tinp->b_cont) { 

20 dina_addr - vtop (tinp->b_rptr) ; 

21 dina_len - tinp->b_wptr - tmp->b__rptr; 

22 xxx^do^dma (dina__addr, dna^len) ; 

23 ) 

24 f reemsg (mp) ; 

25 break; 



26 } 

27 } 

28 } 
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NAME 



putbq - place a message at the head of a queue 



SYNOPSIS 



♦include <sys/stream.h> 

int putbq (queue_t ^cj, inblk_t *bp) ; 



ARGUMENTS 



Pointer to the queue. 
Pointer to the message block. 



bp 



DESCRIPTION 

putbq places a message at the beginning of the appropriate section of the mes- 
sage queue. There are always sections for high priority and ordinary messages. 
If other priority bands are used, each will have its own section of the queue, in 
priority band order, after high priority messages and before ordinary messages, 
putbq can be used only for ordinary and priority band messages. High priority 
messages are not subject to flow control, and so cannot be put back on the queue. 

This fimction is usually called when bcanput(D3DK) or canput(D3DK) deter- 
mines that the message cannot be passed on to the next stream component. The 
flow control parameters are updated to reflect the change in the queue's status. If 
QNOENB is not set, the service routine is enabled. 

RETURN VALUE 

putbq returns 1 on success and 0 on failure. 



Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
STREAMS Programmer's Guide, Chapter 5, "Messages" 
bcanput(D3DK), canput(D3DK), getq(D3DK), putq(D3DK) 
EXAMPLE 

See the buf call(D3DK) function page for an example of putbq. 
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NAME 

putctl - send a control message to a queue 

SYNOPSIS 

♦include <sys/ St ream. h> 

int putctl (queue_t *q, int type) ; 
ARGUMENTS 

q Queue to which the message is to be sent. 

type Message type (must be control, not data type), 
DESCRIPTION 

putctl tests the type argument to make sure a data type has not been specified, 
and then attempts to allocate a message block. putctl fails if type is 
M_DATA,M__DELAY, M_PROTO, or M_PCPROTO, or if a message block cannot be 
allocated. If successful, putctl calls the put(D2DK) routine of the queue 
pointed to by q, 

RETURN VALUE 

On success, 1 is returned. If type is a data type, or if a message block cannot be 
allocated, 0 is returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
datainsg(D3DK), putctll(D3DK) 
EXAMPLE 

The send_ctl routine is used to pass control messages downstream. M_BREAK 
messages are handled with putctl (line 11). putctll (line 16) is used for 
M__DELAY messages, so that parm can be used to specify the length of the delay. 
In either case, if a message block cannot be allocated a variable recording the 
number of allocation failures is incremented (lines 12, 17). If an invalid message 
type is detected, cmn_err(D3DK) panics the system (line 21). 



1 void 

2 aend_ctl (wrq, type, parm) 

3 queue_t *wrq; 

4 unchar type; 

5 unchar parm; 

6 { 

7 extern int num_alloc_fail; 
8 

9 switch (type) { 

10 case M_BREAK: 

11 if (!putctl(wrq->q_next, M_BREAK) ) 

12 num_alloc__fail++; 

13 break; 
14 

15 case M_DELAY: 

16 if ( 'putctll (wrq->q_next, M__DELAY, parm)) 
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17 num_alloc_fall++; 

18 break; 
19 

20 default: 

21 cinn__err (CE_PANIC, "send_ctl: bad message type passed"); 

22 break; 

23 ) 

24 ) 
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NAME 

putctll - send a control message with a one-byte parameter to a queue 

SYNOPSIS 

♦include <sys/stream.h> 

int putctll (queue_t int type, int p) ; 
ARGUMENTS 

q Queue to which the message is to be sent. 

type Type of message. 
p One-byte parameter. 

DESCRIPTION 

putctll, like putctl(D3DK), tests the type argument to make sure a data type 
has not been specified, and attempts to allocate a message block. The p parame- 
ter can be used, for example, to specify how long the delay will be when an 
M_DELAY message is being sent, putctll fails if type is MJDATA, M__PROTO, 
or M_PCPROTO, or if a mesage block cannot be allocated. If successful, putctll 
calls the put(D2DK) routine of the queue pointed to by q, 

RETURN VALUE 

On success, 1 is returned. 0 is returned if type is a data type, or if a message 
block cannot be allocated. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
allocb(D3DK), datainsg(D3DK), putctl(D3DK) 
EXAMPLE 

See the putctl(D3DK) ftmction page for an example of putctll. 
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NAME 

putnext - send a message to the next queue 

SYNOPSIS 

♦include <sys/stream.h> 
♦include <sys/ddi.h> 

int putnext (queue_t *q, niblk_t *mp) ; 
ARGUMENTS 

q Pointer to the queue from which the message mp will be sent. 

mp Message to be passed. 

DESCRIPTION 

The putnext function is used to pass a message to the put(D2DK) routine of 
the next queue in the stream. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
EXAMPLE 

See the allocb(D3DK) function page for an example of putnext. 
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NAME 

putq - put a message on a queue 

SYNOPSIS 

♦include <sys/stream.h> 

int putq (queue_t ^cf, inblk_t *bp) ; 
ARGUMENTS 

q Pointer to the queue to which the message is to be added. 

bp Message to be put on the queue. 

DESCRIPTION 

putq is used to put messages on a driver's queue after the module's put routine 
has finished processing the message. The message is placed after any other mes- 
sages of the same priority, and flow control parameters are updated. If QNOENB 
is not set, the service routine is enabled. If no processing is done, putq can be 
used as the module's put routine. 

RETURN VALUE 

putq returns 1 on success and 0 on failure. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
putbq(D3DK), qenable(D3DK), rmvq(D3DK) 
EXAMPLE 

See the datainsg(D3DK) function page for an example of putq. 
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NAME 

qenable - enable a queue 

SYNOPSIS 

tinclude <sys/stream.h> 
♦include <sys/ddi.h> 

void qenable(queue_t *q) ; 
ARGUMENT 

q Pointer to the queue to be enabled. 

DESCRIPTION 

qenable puts the queue pointed to by q on the linked list of those whose service 
routines are ready to be called by the STREAMS scheduler. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
EXAMPLE 

See the dupb(D3DK) function page for an example of the qenable. 
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NAME 

qreply - send a message on a stream in the reverse direction 

SYNOPSIS 

♦include <sys/stream.h> 

void qreply (queue_t *q, inblk_t *bp) ; 

ARGUMENTS 

q Pointer to the queue. 

bp Pointer to the message to be sent in the opposite direction. 

DESCRIPTION 

qreply sends a message on a stream in the opposite direction from q. It calls the 
0THERQ(D3DK) function to find module partner, and passes the message by 
calling the put(D2DK) routine of the next queue in the stream after ^s partner. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
STREAMS Programme/ s Guide 
0THERQ(D3DK), putnext(D3DK) 
EXAMPLE 

This example depicts the canonical flushing code for STREAMS drivers. The 
driver has a write srv(D2DK) (service) routine that may have messages on the 
queue. If it receives an M_FLUSH message (line 6), and if the FLUSHW bit is on in 
the first byte of the message (line 7), then the write queue is flushed (line 8) and 
the FLUSHW bit is turned off (line 9). If the FLUSHR bit is on, then the read 
queue is flushed (line 12) and the message is sent back up the read side of the 
stream with the qreply(D3DK) fimction Qine 13). If the FLUSHR bit is off, then 
the message is freed (line 15). See the example for f lushq(D3DK) for the canon- 
ical flushing code for modules. 

qreply does two things. First, it calls the OTHERQ function to change pointer q 
to the module's other queue(D4DK) structure, reversing the direction of the 
flow. Then it uses that queue's q_next pointer to call the next module's 
put(D2DK) routine with the M_IOCNAK message. 



1 xx3twput<q, mp) 

2 queue_t *q; 

3 inblk__t *inp; 

4 { 

5 switch (inp->b_datap-Xib_type) { 

6 case M_FLUSH: 

7 if (*mp->b_rptr & FLUSHW) { 

8 flushq(q, FLUSHALL) ; 

9 *mp->b_rptr &- -FLUSHW; 
10 ) 
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11 if (*nip->b_rptr & FLUSHR) { 

12 f luahq (RD (q> , FLUSHALL) ; 

13 qreply(q, mp) ; 

14 } else { 

15 freemsgCmp) ; 

16 ) 

17 break; 

18 } 



19 } 
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NAME 

qsize - find the number of messages on a queue 

SYNOPSIS 

♦include <sys/stream.h> 

int qsize (queue^t *q) ; 

ARGUMENT 

q Queue to be evaluated. 

DESCRIPTION 

qsize evaluates the queue q and returns the nimiber of messages it contains. 
RETURN VALUE 

If there are no message on the queue, qsize returns 0. Otherwise, it returns 
the integer representing the number of messages on the queue. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
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NAME 

RD - get pointer to the read queue 

SYNOPSIS 

♦include <sys/stream.h> 
♦include <sys/ddi.h> 

queue_t RD (queue_t *q) ; 
ARGUMENT 

q Pointer to the write queue whose read queue is to be returned. 

DESCRIPTION 

The RD function accepts a write queue pointer as an argument and returns a 
pointer to the read queue of the same module. 

CAUTION: Make sure the argument to this function is a pointer to a write queue. 
RD will not check for queue type, and a system panic could result if it is not the 
right tyipe, 

RETURN VALUE 

The pointer to the read queue. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STBUEAMS" 
WR(D3DK) 
EXAMPLE 

See the qreply(D3DK) function page for an example of RD. 
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NAME 

rmalloc - allocate space from a private space management map 

SYNOPSIS 

♦include <sys/xnap.h> 
♦include <sys/ddi.h> 

unsigned long rmalloc (struct map *wp, long size); 
ARGUMENTS 

mp Memory map from where the resource is drawn. 

size Number of units of the resource. 

DESCRIPTION 

rmalloc is used by a driver to allocate space from a previously defined and ini- 
tialized private space management map. The map itself is declared as a structure 
using the driver prefix iri the form prefixmap. Memory is initially allocated for the 
map either by a data array, or by the kmem_alloc(D3DK) function, rmalloc 
is one of five fimctions used for private map management. The other functions 
include 

rmf ree Return previously allocated space to a map. 

rminit Define a map structure and initialize a map table, 

rmwant Return the number of processes waiting for free space, 

rmsetwant Increment the count of the ntimber of processes waiting for 
free space in the map. 

The rmalloc function allocates space from a memory map in terms of arbitrary 
units. The system maintains the map structure by size and index, computed in 
units appropriate for the memory map. For example, units may be byte 
addresses, pages of memory, or blocks. The elements of the memory map are 
sorted by index, and the system uses the size member to combine adjacent objects 
into one memory map entry. The system allocates objects from the memory map 
on a first-fit basis. The normal return value is an unsigned long set to the value 
of m_addr from the map structure. 

RETURN VALUE 

Under normal conditions, rmalloc returns the base of the allocated space. Oth- 
erwise, rmalloc function returns a 0 if all memory map entries are already 
allocated. 

LEVEL 

Base 

Interrupt if rmwant is not set 
SEE ALSO 

BCI Driver Development Guide, Chapter 6, "Input /Output Operations" 
dma_pageio(D3D), rminit(D3DK), rmwant(D3DK), rmfree(D3DK) 
EXAMPLE 

The following example is a simple memory map, but it illustrates the principles of 
map management. A driver initializes the map table by calling both the 
rminit(D3DK) and rmf ree(D3DK) fimctions. rminit(D3DK) establishes the 
number of slots or entries in the map, and rmf ree to initialize the total buffer 
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area the map is to manage. The following example is a fragment from a 
hypothetical start routine and illustrates the following procedures: 

Declaration of the map structure (line 4). The defined map array must be 
initialized to zero before calling rminit. 

The use of kmem_alloc(D3DK) to allocate memory for the map. This 
example panics the system if the required amount of memory can not be 
allocated (lines 10-14). 

The use of xnapinit to configure the total number of entries in the map, 
and of rmfree to configure the total buffer area. 

1 #def ine XXJO^SIZE 12 

2 ideflne XX_BUFSIZE 2560 
3 

4 struct map xx_inap[XXJHAPSIZE] ; /* Space management map for *l 



5 /* a private buffer */ 

6 xx_start() 

7 /* 

8 * Allocate private buffer. If insufficient memory, 

9 * display message and halt system. 

10 */ 

11 { 

12 register caddr_t bp; 

13 if ((bp - kroem_alloc(XX_BDFSIZE, KM_NOSLEEP) — 0) { 
14 

15 cmn__err (CE_PANIC, "xx__start: kmem^^alloc failed before %d buffer 

allocation-, XX__BUFSIZE) ; 

16 ) /* endif */ 

17 /* 

18 * Initialize space management map with number 

19 * of slots in map. 

20 */ 

21 rminit (xx__map, ^__MAPSIZE) ; 

22 /* 

23 * Initialize space management map with total 

24 * buffer area it is to manage. 

25 */ 

26 rmfree (xxjnap, XXJ3UFSIZE, bp); 



The rinalloc(D3DK) function is then used by the driver's read or write rou- 
tine to allocate buffers for specific data transfers. If the appropriate space cannot 
be allocated, the rmsetwant(D3DK) function is used to wait for a free buffer 
and the process is put to sleep until a buffer is available. When a buffer becomes 
available, the rinfree(D3DK) function is called to return the buffer to the map 
and to wake the sleeping process (no wakeup(D3DK) call is required). The 
uioniove(D3DK) function is used to move the data between user space and local 
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drivet memory. The device then moves data between itself and local driver 
memory through DMA. 

The next example illustrates the following procedures: 

The size of the I/O request is calculated and stored in the size variable 
(lines 14-15). 

While buffers are available, buffers are allocated through the rmalloc 
function using the size value (line 25). 

If there are not enough buffers free for use, the rinsetwant(D3DK) func- 
tion is called, and the prociesis is put to sleep (lines 26-28). When a buffer 
becomes available, the rmf reie(D3DK) function returns the buffer to the 
map and wakes the process. 

The uiomove(D3DK) function is used to move data to the allocated 
buffer (line 35). 

If the address passed to the uiomove function is invalid, the rmf ree 
function is called to release the previously alibcited buffer, and an 
EFAULT error is returned. 

1 fdefine XX_MAPPRIO (PZERO + 6) 

2 fdefine XX__MAPSIZE 12 

3 #define XX__BUFSIZE 2560 

4 fdefine XXJMAXSIZE (XX_BUFSIZE / 4) 

6 struct map xx_map [XX_MAPSIZE] ; /* Private buffer space map */ 



7 char xx_buf fertXX_BUFSIZE] ; /* driver xx_ buffer area */ 

8 read(dev, uio_p, cred__p) 

9 dev_t dev; 

10 uio__t uio_j>; /* Pointer to uio structure for I/O */ 

11 cred__t credjp; 
12 

13 register caddr__t addr; 

14 register int size; 

15 size - ihin (COUNT, XXJIAXSIZE) ; /* Break large I/O request */ 

16 /* into small ones */ 

17 /* 

18 * G^t buffer. If space is not available, then 

19 * request a wakeup when space is returned. Wait 

20 * for space; rmf ree will check rmsetwant and 

21 * supply the wakeup call . 

22 */ 

23 oldlevel - spl4(); 
24 

25 while ((addr— (caddr_t) rmalloc (xxjnap, size)) — NULL) { 

26 rmsetwant (xx_jnap) 

27 sleep (xx_map, XX_MAXPRIQ); 

28 ) /* endwhile */ 

29 splx (oldlevel); 
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30 

31 /* 

32 * Move d^ta to j^uffer. If invalid address Is found, 

33 * return buffer to map and return error code. 

34 */ 

35 if (uiomove (addr, size, UIO_READ, uio__p) -1) { 

36 oldlevel - spl4(); 

37 rmf ree(xx_map, size, addr) ; 

38 splx( oldlevel); 
3 9 return ( EFAULT ) ; 
40 } /* endif */ 
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NAME 

rmf ree - free space back into a private space management map 

SYNOPSIS 

tinclude <sys/inap.h> 
♦include <sys/ddi.h> 

void rmf ree (struct map *mp, long size, unsigned long index); 

ARGUMENTS 

*tnp Pointer to the map(D4DK) structure. 

size Number of units being freed. 

index Index of the first unit of the allocated resource. 
DESCRIPTION 

rxnfree releases space back into a private space management map. It is the 
opposite of rmalloc(D3DK), which allocates space that is controlled by a private 
map structure. 

Drivers may define private space management buffers for allocation of memory 
space, in terms of arbitrary units, using the rmalloc(D3DK), rmf ree and 
rminit(D3DK) functions. "Rie drivers must include the file map . h. The system 
maintains the memory map list structure by size and index, computed in units 
appropriate for the memory map. For example, units may be byte addresses, 
pages of memory, or blocks. The elements of the memory map are sorted by 
index, and the system uses the size member so that adjacent objects are combined 
into one memory map entry. The system allocates objects from the memory map 
on a first-fit basis, rmf ree frees up unallocated memory for re-use. 

RETURN VALUE 

None. However, if the m_addr member of the map structure is returned as 0, 
the following warning message is displayed on the console: 

WARNING: rmf ree map overflow mp lost sizg items at index 

where tnp is the hexadecimal address of the map structure, size is the decimal 
number of buffers freed, and index is the decimal address to the first buffer unit 
freed. 

LEVEL 

Base or Interrupt 
SEE ALSO 

rmalloc(D3DK), rminit(D3DK), rmwant(D3DK) 

EXAMPLE 

See rmalloc(D3DK). 
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NAME 

rminit - initialize a private space management map 

SYNOPSIS 

. # include <sys/map.h> 
♦include <sys/ddi.h> 

void rminit (struct map *mp, unsigned long mapsize) ; 
ARGUMENTS 

*mp Pointer to the memory map from where the resource is drawn. 

rmpsize Number of entries for the memory map table. 
DESCRIPTION 

The rminit function initializes a private map structure that can be used for the 
allocation of memory space. The map itself is declared as a structure using the 
driver prefix in the form prefixmap. Memory is initially allocated for the map 
either by a data array, or by the kmem_alloc(D3DK) fimction. 

The driver must initialize the map structure by calling rminit. However, 
rminit does not cause the memory map entries to be labeled available. This 
must be done through rmf ree(D3DK) before objects can actually be allocated 
from the memory map. 

The system maintains the memory map list structure by size and index, computed 
in units appropriate for the memory map. Units may be byte addresses, pages of 
memory, or blocks. The elements of the memory map are sorted by index. 

Two memory map table entries are reserved for internal system use and they are 
not available for memory map use. 

NOTE: The map array must be initialized to zero before calling rminit. 

RETURN VALUE 
None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 6, "Input/Output Operations" 
rmalloc(D3DK), rmwant(D3DK), rmfree(D3DK), rmsetwant(D4DK) 

EXAMPLE 

See rmalloc(D3DK). 
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NAME 

rmsetwant - set the map's wait flag for a wakeup 
SYNOPSIS 

♦include <sys/map.h> #include <sys/ddi.h> 
void rmsetwant (struct map *mapj)) ; 
ARGUMENTS 

mapj> Pointer to the map the driver is waiting for. 
DESCRIPTION 

The rmsetwant fimction increments the counter on the wait flag of the map 
pointed to by map_p. It is typically called from the driver's read or write rou- 
tine after an unsuccessful attempt to allocate space from the map using 
rmalloc(D3DK). 

Typically, a driver will sleep on map_p after calling rmsetwant. When the 
rmfree function returns space to the map, it calls wakeup(D3DK). 

RETURN VALUE 

None 

LEVEL 

Base only 
SEE ALSO 

rmalloc(D3DK), rmfree(D3DK), rminit(D3DK), rmwant(D3DK), 
map(D4DK) 

EXAMPLE 

See rmalloc(D3DK). 
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NAME 

rmvb - remove a message block from a message 

SYNOPSIS 

♦include <sys/stream.h> 

mblk^t *rmvb (mblkj: *mp, iriblk_t *bp) ; 
ARGUMENTS 

*mp Message from which a block is to be removed, mblk^t is an 
instance of the xnsgb(D4DK) structure. 

bp Message block to be removed. 

DESCRIPTION 

rxnvb removes a message block (bp) from a message (mp), and returns a pointer to 
the altered message. The message block is not freed, merely removed from the 
message. It is the module or driver's responsibility to free the message block. 

RETURN VALUE 

If successful, a pointer to the message (minus the removed block) is returned. 
The pointer is NULL if bp was the only block of the message before rxnvb was 
called. If the designated message block (bp) does not exist, -1 is returned. 

LEVEL 

Base or Interrupt 
EXAMPLE 

This routine removes all zero-length M_DATA message blocks from the given mes- 
sage. For each message block in the message, save the next message block (line 
10). If the current message block is of type M__DATA and has no data in its buffer 
(line 11), then remove it from the message (line 12) and free it (line 13). In either 
case, continue with the next message block in the message (line 16). 

1 void 

2 xxclean(inp) 

3 mblk_t *mp; 

4 { 

5 inblk__t *tmp; 

6 niblJc_t *ninp; 
7 

8 tinp - mp; 

9 while (tmp) { 

10 nmp - tmp->b_next; 

11 if ( (tmp->b__datap->db_type M_DATA) && 

(tinp->b__rptr tinp->b__wptr> ) { 

12 rmvb (mp, tmp) ; 

13 f reeb (tmp) ; 

14 ) 

15 tmp - nmp; 

16 ) 

17 ) 
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NAME 

rmvq - remove a message from a queue 

SYNOPSIS 

♦include <sys/streain.h> 

void rmvq(queue_t iriblk_t *mp) ; 
ARGUMENTS 

q Queue containing the message to be removed. 

mp Message to remove. 

DESCRIPTION 

rmvq removes a message from a queue. A message can be removed from any- 
where on a queue. To prevent modules and drivers from having to deal with the 
internals of message linkage on a queue, either rmvq or getq(D3DK) should be 
used to remove a message from a queue. 

CAUTION: Make sure that the message mp exists to avoid a possible system 
panic. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
EXAMPLE 

This code fragment illustrates how one may flush one type of message from a 
queue. In this case, only M__PROTO T__DATA__IND messages are flushed. For each 
message on the queue, if it is an M_PROTO message (line 8) of type T_DATA_IND 
(line 10), save a pointer to the next message (line 11), remove the T_DATA__IND 
message (line 12) and free it (line 13). Continue with the next message in the list 
(line 19). 

1 mblk^t *mp; 

2 inblk_t *nmp; 

3 queue_t *q; 

4 iinion T__priinitives *tp; 
5 

6 mp - q->q_first; 

7 while (mp) { 



8 if (mp->b__datap->db__type — M_PROTO) { 

9 tp - (union T__primitives *)mp~>b_rptr; 

10 if (tp->type — T_DATA_IND) { 

11 nmp - mp->b_next; 

12 rmvq(q, mp) ; 

13 freemsg(mp); 

14 mp - nmp; 

15 } else { 

16 mp - mp->b__next; 

17 } 
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18 } else ( 

19 n»p - inp->b_next; 

20 } 

21 ) 
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NAME 

rmwant - wait for free memory 

SYNOPSIS 

tinclude <sys/map.h> 
♦include <sys/ddi.h> 

unsigned long rmwant (struct map *mflpj7) / 
ARGUMENT 

map J) Pointer to the inap(D4DK) structure on which the driver is waiting for 
space. 

DESCRIPTION 

The rmwant function returns the number of processes waiting for free space in 
the map. 

RETURN VALUE 

The nimiber of processes waiting for free space in the map. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 6, "Input/Output Operations" 

rmalloc(D3DK), rminit(D3DKX rmfree(D3DK), rmsetwant(D3DK), 
map(D4DK) 
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NAME 

SAMESTR - test if next queue is same type 

SYNOPSIS 

♦include <sys/stream.h> 

int SAMESTR (queue_t '^q) ; 

ARGUMENT 

*q Pointer to the queue. 

DESCRIPTION 

The SAMESTR function is used to see if the next queue in a stream (if it exists) is 
the same type as the current queue (that is, both are read queues or both are 
write queues). 

RETURN VALUE 

SAMESTR returns 1 if the next queue is the same type as the current queue. It 
returns 0 if the next queue does not exist or if it is not the same type. 

LEVEL 

Base or Interrupt 

SEE ALSO 

0THERQ(D3DK) 
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NAME 

sleep - suspend process activity pending execution of an event 

SYNOPSIS 

tinclude <sys/types .h> 
♦include <sys/param.h> 

int sleep (caddr_t ^nf, int priority); 
ARGUMENTS 

event Address (signifying an event) for which the process will wait to be 
updated. 

priority Priority that is assigned to the process when it is awakened. If priority 
is ORed with the defined constant PCATCH, the sleep function does 
not call long jmp on receipt of a signal. Instead, it returns the value 
1 to the calling routine. 

DESCRIPTION 

sleep suspends execution of a process to await certain events such as reaching a 
known system state in hardware or software. For instance, when a process wants 
to read a device and no data is available, the driver may need to call sleep to 
wait for data to become available before returning. This causes the kernel to 
suspend executing the process that called sleep and schedule another process. 
The process that called sleep can be restarted by a call to the wakeup(D3DK) 
function with the same event specified as that used to call sleep. 

A driver (with data stored in local variables) may call sleep while waiting for 
an event to occur. Make sure another process will not interrupt the driver and 
overwrite the local variables. 

The event address used when calling sleep should be the address of a kernel 
data structure or one of the driver's own data structures. The sleep address is 
an arbitrary address that has no meaning except to the corresponding wakeup 
function call. This does not mean that any arbitrary kernel address should be 
used for sleep. Doing this could conflict with other, unrelated sleep/wakeup 
operations in the kernel. A kernel address used for sleep should be the address 
of a kernel data structure directly associated with the driver I/O operation (for 
example, a buffer assigned to the driver). 

Before a process calls sleep, the driver usually sets a flag in a driver data struc- 
ture indicating the reason why sleep is being called. 

The ;?nonfy argument, called the sleep priority, is used for scheduling purposes 
when the process awakens. This parameter has critical effects on how the process 
that called sleep reacts to signals. If the numerical value of the sleep priority 
is less than or equal to the constant PZERO (defined in the sys/param.h header 
file), then the sleeping process will not be awakened by a signal. However, if the 
nimierical value is greater than PZERO, the system awakens the process that 
called sleep prematurely (that is, before the event on which sleep was called 
occurred) on receipt of a non-ignored, non-held signal. In this case, it returns the 
value 1 to the calling routine if PCATCH is set; otherwise it does a long jn^ and 
never returns to the driver. If the event occurred, 0 is returned. 
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To pick the correct sleep priority, base yoiir decision on whether or not the 
process should be awakened on the receipt of a signal. If the driver calls sleep 
for an event that is certain to happen, the driver should use a priority numeri- 
cally less than or equal to PZERO. (However, you should only use priorities less 
than or equal to PZERO if your driver is crucial to system operation.) If the 
driver calls sleep while it awaits an event that may not happen, use a priority 
numerically greater than PZERO. 

An example of an event that may not happen is the arrival of data from a remote 
device. When the system tries to read data from a terminal, the terminal driver 
might call sleep to suspend the current process while waiting for data to arrive 
from the terminal. If data never arrives, the sleep call will never be answered. 
When a user at the terminal presses the BREAK key or hangs up, the terminal 
driver interrupt handler sends a signal to the reading process, which is still exe- 
cuting sleep. The signal causes the reading process to finish the system call 
without having read any data. If sleep is called with a priority value that is not 
awakened by signals, the process can be awakened only by a specific wakeup 
call. If that wakeup call never happened (the user himg up the terminal), then 
the process executes sleep until the system is rebooted. 

Another important criteria for selecting the appropriate priority is how important 
the event or resource being waited for is to overall system performance. For 
example, disk I/O is often a bottleneck, so the priority for disk I/O is higher than 
most other priorities. In contrast, terminal I/O is a much lower priority. The 
sooner the process runs, the faster the resource will be used and freed again. 

Drivers calling sleep must occasionally perform cleanup operations before 
returning. Typical items that need cleaning up are locked data structures that 
should be imlocked when the system call completes. This is done by ORing prior- 
ity with P CATCH and executing sleep. If sleep returns a 1, then you can 
cleanup any locked structures or free any allocated resources, and return. CAU- 
TION: If sleep is called from the driver strategy(D2DK) routine, you should 
OR the priority argument with PCATCH or select a priority of PZERO or less. 

RETURN VALUE 

If the sleep priority argument is ORed with the defined constant PCATCH, the 
sleep function does not call longjnp on receipt of a signal; instead, it returns 
the value 1 to the calling routine. If the process put in a wait state by sleep is 
awakened by an explicit wakeup call rather than by a signal, the sleep call 
returns 0. 

LEVEL 

Base Only (Do not call from an interrupt routine) 
SEE ALSO 

BCI Driver Development Guide, Chapter 10, "S5mchronizing Hardware and 
Software Events" 

delay(D3DK), biodone(D3DK), biowait(D3DK), timeout (D3DK), 
untimeout(D3DK), wakeup(D3DK) 
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EXAMPLE 

See the untixneout(D3DK) function page for an example of sleep. 
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NAME 

spl - block/ allow interrupts 

SYNOPSIS 

♦include <sys/inline.h> 



int 


splOO; 


int 


spllO; 


int 


spl4(); 


int 


spl5(); 


int 


spl6(); 


int 


spl7(); 


int 


splvmO ; 


int 


splhiO ; 


int 


splstr 0 ; 


int 


splttyO; 


int 


splx(int oldlevel) ; 


ARGUMENT 





oJdlevel Last set priority value (only splx has an input argument). 
DESCRIPTION 

spl blocks or allows interrupts. When a process is executing code in a driver, 
the system will not switch context from that process to another executing process 
unless it is explicitly told to do so by the driver. This protects the integrity of the 
kernel and driver data structures. However, the system does allow devices to 
interrupt the processor and handle these interrupts immediately. 

The integrity of system data structures would be destroyed if an interrupt 
handler were to manipulate the same data structures as a process executing in the 
driver. To prevent such problems, the kernel provides the spl functions allow- 
ing a driver to set processor execution levels, prohibiting the handling of inter- 
rupts below the level set. 

The selection of the appropriate spl function is important. The execution level 
to which the processor is set must be high enough to protect the region of code; 
but this level should not be so high that it unnecessarily locks out interrupts that 
need to be processed quickly. A hardware device is assigned to an interrupt 
priority level depending on the type of device. By using the appropriate spl 
function, a driver can inhibit interrupts from its device or other devices at the 
same or lower interrupt priority levels. 

The spl command changes the state of the processor status word (PSW). The 
PSW stores the current processor execution level, in addition to information relat- 
ing to the operating system internals. The spl functions block out interrupts 
that come in at a priority level at or below a machine-dependent interrupt prior- 
ity level. The spl functions include the following: 

splO Restores all interrupts when executing on the base level. A driver 
routine may use splO when the routine has been called through 
a system call; that is, if it is known that the level being restored is 
indeed at base level. 
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spll Used in context and process switch to protect critical code. 

spl4 Used in character drivers to protect critical code. 

spl5 Used in character drivers to protect critical code (this function has 
the same effect as spl4). 

spl6 Used in block drivers to protect critical code. 

spl7 Used in any type of driver to mask out all interrupts including the 
clock, and should be used very sparingly. 

I splvm Used in memory management code to protect critical regions. 

splhi Used in any type of driver to mask out all interrupts including the 
clock, and should be used very sparingly. (This function is identi- 
cal to spl7.) 

spltty Used by a TTY driver to protect critical code. 

splstr Used to protect STREAMS driver and module critical regions of 
code. This is defined to be high enough to block interrupts from 
the highest priority STREAMS device, splstr is mapped to 
spltty. 

splx Used to terminate a section of protected critical code. This func- 
tion restores the interrupt level to the previous level specified by 
its argument oldlevel. 

NOTE: spl functions should not be used in interrupt routines unless you save 
the old interrupt priority level in a variable as it was returned from an spl call. 
Later, splx must be used to restore the saved old level. Never drop the inter- 
rupt priority level below the level at which an interrupt routine was entered. For 
example, if an interrupt routine is entered at the interrupt priority level of an 
spl 6, do not call splO through spl 5 or the stack may become corrupted. 

RETURN VALUE 

All spl functions (except splx) return the former priority level. 
EXAMPLE 

See the untiineout(D3DK) function page for an example of spl. 
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NAME 

strlog - submit messages to the log driver 

SYNOPSIS 

# include <sys/stream.h> 
♦include <sys/strlog.h> 
♦include <sys/log.h> 

int strlog (short mid, short sid, char level, unsigned short flags, 
char */mi, unsigned arg2, ...) ; 

ARGUMENTS 

mid Identification number of the module or driver submitting the message. 

sid Identification number for a particular minor device. 

level Tracing level for selective screening of low priority messages. 

flags Valid flag values are: 

SL_ERROR Message is for error logger. 
SL_TRACE Message is for trace. 

SL_NOTIFY Mail copy of message to system administrator. 
SL_CONSOLE 

Log message to console. 
SL_FATAL Error is fatal. 
SL__WARN Error is a warning. 
SL__NOTE Error is a notice. 

fmt printfOS) style format string. %s, %e, %g, and %G formats are not 

allowed. 

argl Zero or more arguments to printf. 
DESCRIPTION 

Strlog submits formatted messages to the log(7) driver. The messages can be 
retrieved with the getmsg(2) system call. The flags argument specifies the type 
of the message and where it is to be sent, st raced M) receives messages from 
the log driver and sends them to the standard output. strerr(lM) receives 
error messages from the log driver and appends them to a file called 
/ var/adm/ St reams/error. mm-(W, where mm-dd identifies the date of the error 
message. 

RETURN VALUE 

strlog returns 0 if the message is not seen by all the readers, 1 otherwise. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Dni7er DCT;etop7neni Gttiie, Chapter 12, ''Error Reporting'' 
log(7) 
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NAME 

strqget - get information about a queue or band of the queue 

SYNOPSIS 

♦include <sys/stream.h> 

int strqget (queue_t *q, qf ields_t what, unsigned char pri, 
long *valp) ; 

ARGUMENTS 

cf Pointer to the queue 

what Which field of the queue structure to return information about. Valid 
values are specified in stream. h: 



typedef enum qfields { 






QHIWAT 


= 0, 


/* 


q_hiwat or qb^hiwat */ 


QLOWAT 


= Ir 


/* 


q_lowat or qb_lowat */ 


QMAXPSZ 


= 2r 


/* 


q^^maxpsz */ 


QMINPSZ 


= 3, 


/* 


qjnihpsz */ 


OCOUNT 


- 4, 


/* 


q^count or qb_count */ 


QFIRST 


= 5, 


/* 


q^first or qb__first */ 


QLAST 


= Sr 


/* 


q^last or qb_last */ 


QFLAG 


= 7, 


/* 


q_flag or qb__flag */ 


QBAD 


= 8 







} qfields_t; 
pri Priority of request. 

valp The value for the requested field. 
DESCRIPTION 

strqget gives drivers and modules a way to get information about a queue or a 
particular band of a queue without directly accessing STREAMS data structures. 

RETURN VALUE 

On success, 0 is returned. An error number is returned on failure. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, ChsLpter 7, "STREAMS" 
strqset(D3DK) 
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NAME 

strqset - change information about a queue or band of the queue 

SYNOPSIS 

♦include <sys/stream.h> 

int strqset (queue_t *q, qf ields_t what, unsigned char pri, 
long *ml) 'r 

ARGUMENTS 

q Pointer to the queue. 

what Which field of the queue structure to return information about. Valid 
values are specified in St ream, h: 

typedef enum qfields { 



QHIWAT 




0, 


/* 


q_hiwat or qb_hiwat */ 


QLOWAT 


as 


1, 


/* 


cj_lowat or qb_lowat */ 


QMAXPSZ 




2, 


/* 


q_maxpsz */ 


QMINPSZ 




3, 


/* 


q_inlnpsz */ 


QCOUNT 




4, 


/* 


q_count or qb_count */ 


QFIRST 




5, 


/* 


q_first or qb_first */ 


QLAST 




6, 


/* 


q_last or qb_last */ 


QFLAG 




7, 


/* 


q_£lag or qb_flag */ 


QBAD 




8 







} qfields_t; 
pri Priority of request. 

val The value for the field to be changed. 

DESCRIPTION 

strqset gives drivers and modules a way to change information about a queue 
or a particular band of a queue without directly accessing STREAMS data struc- 
tures. The fields that can be returned are defined in the enumerated type 
qfields. qfields defines the following fields: 

RETURN VALUE 

On success, 0 is returned. An error number is returned on failure. If the what 
field is read-only, EPERM is returned and the field is left imchanged. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
strqget(D3DK) 
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NAME 

testb - check for an available buffer 

SYNOPSIS 

♦include <sys/stream.h> 

int testb (int size, int pri) ; 

ARGUMENTS 

size Size of the requested buffer. 

pri Priority of the allocb request. 

DESCRIPTION 

testb checks to see if an allocb(D3DK) call is likely to succeed if a buffer of 
size bytes at priority pri is requested. Even if testb returns successfully, the call 
to allocb can fail. 

RETURN VALUE 

Returns 1 if a buffer of the requested size is available, and 0 if one is not. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, "STREAMS" 
allocb(D3DK) , buf call(D3DK) 
EXAMPLE 

In a srv(D2DK) (service) routine, if copymsg(D3DK) fails (line 6), the message 
is put back on the queue (line 7) and a routine, tryagain, is scheduled to be 
run in one tenth of a second (HZ/ 10). Then the service routine returns. 

When the timeout (D3DK) function runs, if there is no message on the front of 
the queue, it just returns. Otherwise, for each message block in the first message, 
check to see if an allocation would succeed. If the number of message blocks 
equals the number we can allocate, then enable the service procedure. (Otherwise, 
reschedule tryagain to run again in another tenth of a second. Note that 
tryagain is merely an approximation. Its accounting may be faulty. Consider 
the case of a message comprised of two 1024-byte message blocks. If there is 
only one free 1024-byte message block and no free 2048-byte message blocks, then 
testb will still succeed twice. If no message blocks are freed of these sizes 
before the service procedure runs again, then the copymsg(D3DK) will still fail. 
The reason testb is used here is because it is significantly faster than calling 
copyxnsg. We must minimize the amount of time spent in a timeout routine. 

1 xxxsrv(q) 

2 queue_t *q; 

3 { 

4 inblk__t *inp; 

5 inblk_t *ninp; 

6 if ((nmp - copymsg (mp) ) »» NULL) { 

7 putbq(q, mp) ; 

8 timeout (tryagain, (long)q, H2/10); 
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9 return; 

10 } 

11 ) 
12 

13 tryagaln(q) 

14 queue_t *q; 

15 { 

16 register int can_alloc - 0; 

17 register int nuin__blks 0; 

18 register mblk__t *mp; 
19 

20 if (!q->q_first) 

21 return; 

22 for (mp - q->qLfirst; mp; mp - inp->b_cont) { 

23 n\iin__blks++; 

24 can_alloc +- testb( (mp-->b__datap->db_liin 

25 mp->b_datap->clb_base) , BPRI__MED>; 

26 } 

27 if (num_blks — can_alloc) 

28 qenable(q); 
2 9 else 

30 timeout (tryagain, (long>q, HZ/10); 

31 } 
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NAME 

timeout - execute a function after a specified length of time 

SYNOPSIS 

#include <sys/types .h> 

int timeout (int i*ftn) {) , caddr_t arg, long ticks); 
ARGUMENTS 

ftn Kernel function to invoke when the time increment expires. 

arg Argument to the function. 

ticks Number of clock ticks to wait before the function is called. 
DESCRIPTION 

The timeout function schedules the specified function to be called after a 
specified time interval. Control is immediately returned to the caller. This is use- 
ful when an event is known to occur within a specific time frame, or when you 
want to wait for I/O processes when an interrupt is not available or might cause 
problems. For example, some robotics applications do not provide a status flag 
for determining when to pump information to the robot's controller. By using 
timeout, the driver can wait a predetermined interval and then begin transfer- 
ring data to the robot. 

The exact time interval over which the timeout takes effect cannot be guaranteed, 
but the value given is a close approximation. The function called by timeout 
must adhere to the same restrictions as a driver interrupt handler. It can neither 
sleep nor use previously set local variables. 

RETURN VALUE 

Under normal conditions, an integer timeout identifier is returned (which may, in 
unusual circumstances, be set to 0). Otherwise, if the timeout table is full, the 
following panic message results: 

PANIC: Timeout table overflow 

The timeout function returns an identifier that may be passed to the 
untimeout(D3DK) function to cancel a pending request. NOTE: No value is 
returned from the called function. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 10, "Synchronizing Hardware and 
Software Events" 

delay(D3DKK), biodone(D3DK), biowait(D3DK), sleep(D3DK), 
untimeout(D3DK), wakeup(D3DK) 

EXAMPLE 

See the bufcall(D3DK) function page for an example of timeout. 
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NAME 

uioroove - copy kernel data using uio(D4DK) structure 

SYNOPSIS 

♦include <sys/types .h> 
♦include <sys/uio.h> 

int uiomove (caddr_t address, long nhytes, enum uio___rw nvflag, 
struct uio * uio_p) ; 

ARGUMENTS 

address Source/destination kernel address of the copy. 
nhytes Number of bytes to copy. 

rwflag Flag indicating read or write operation. Possible values are 
UIO_READand UIO_WRITE. 

uio J) Pointer to the uio structure for the copy. 

DESCRIPTION 

The uiomove function copies nhytes of data to or from the space defined by the 
uio structure (described in uio . h) and the driver. 

The uio_segf Ig member of the uio structure determines the the type of space 
to or from which the transfer being made. If it is set to UIO_SYS SPACE the data 
transfer is between addresses in the kernel. If it is set to UIOJUSERSPACE the 
transfer is between a user program and kernel space. 

In addition to moving the data, uiomove adds the number of bytes moved to 
the iov_base member of the iovec(D4DK) structure, decreases the iov_len 
member, increases the uio_of f set member of the uio structure, and decreases 
the uio_resid member. 

This function does automatic page boundary checking, nhytes does not have to be 
word-aligned. 

CAUTION: If uio_segf Ig is set to UIO_SYSSPACE and address is selected from 
user space, the system panics. 

RETURN VALUE 

uiomove returns 0 upon success or -1 on failure. The driver entry point routine 
through which uiomove was called should return EFAULT if -1 is returned. 

LEVEL 

Base. 
SEE ALSO 

uio(D4DK), ureadc(D3DK), uwritec(D3DK) 

EXAMPLE 

See rmalloc. 
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NAME 

unlinkb - remove a message block from the head of a message 

SYNOPSIS 

♦include <sys/stream.h> 

inblk_t *unlinkb (iriblk_t *mp) ; 

ARGUMENT 

mp Pointer to the message. 

DESCRIPTION 

unlinkb removes the first message block from the message pointed to by mp. A 
new message, minus the removed message block, is returned. 

RETURN VALUE 

If successful, unlinkb returns a pointer to the message with the first message 
block removed. If there is only one message block in the message, NULL is 
returned. 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 7, ''STREAMS" 
linkb(D3DK) 
EXAMPLE 

The routine expects to get passed an M_PROTO T_DATA_IND message. It will 
remove and free the M_PROTO header and return the remaining M_DATA portion 
of the message. 

1 mblk^t * 

2 makedata (mp) 

3 inblk__t *inp; 

4 { 

5 inblk_t *ninp; 
6 

7 nmp - unlinkb (mp) ; 

8 f reeb (mp) ; 

9 return (nmp) ; 
10 } 
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NAME 

untimeout - cancel previous tiroeout(D3DK) function call 

SYNOPSIS 

tinclude <sys/types .h> 

int untimeout (int id) ; 
ARGUMENTS 

id Identification value generated by a previous timeout function call. 

DESCRIPTION 

untimeout cancels a pending timeout(D3DK) request. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 10, "Synchronizing Hardware and 
Software Events" 

delay(D3DK), biodone(D3DK), biowait(D3DK), sleep(D3DK), 
timeout(D3DK), wakeup(D3DK) 

EXAMPLE 

A driver may have to repeatedly request outside help from a computer operator. 
The timeout function is used to delay a certain amount of time between 
requests. However, once the request is honored, the driver will want to cancel 
the timeout operation. This is done with the untimeout fimction. 

In a driver open(D2DK) routine, after the input arguments have been verified, 
the status of the device is tested. If the device is not on-line, a message is 
displayed on the system console. The driver schedules a wakeup(D3DK) call and 
waits for five minutes (line 41). If the device is still not ready, the procedure is 
repeated. 

When the device is made ready, an interrupt is generated. The driver interrupt 
handling routine notes there is a suspended process. It cancels the timeout 
request (line 59) and wakens the suspended process (line 61). 



1 struct intu__device { 

2 /* layout of physical device registers */ 

3 Int control; /* physical device control word */ 

4 Int status; /* physical device status word */ 

5 Int byte_cnt; /* number of bytes to be transferred */ 

6 paddr_t baddr: /* DMA starting physical address */ 

7 }; /* end device */ 
8 

9 struct mtu { 

10 /* magnetic tape unit logical structure */ 

11 struct buf *intu_head; /* pointer to I/O queue head */ 

12 struct buf *intu_tall; /* pointer to buffer I/O queue tail */ 

13 int mtu^flag; /* logical status flag */ 
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14 Int intu__to_ld; /* time out ID number */ 

15 ); /* end mtu */ 
16 

17 extern struct mtu^device *intu_addr [ ] ; /* location of dev regs */ 

18 extern struct mtu mtu_tbl[]; /* location of dev structs */ 

19 extern int mtu_cnt; 



20 mtu__open (dev, flag, type, c_ptr) 

21 dev_t dev; 

22 { 

23 register struct mtu *dp; 

24 register struct mtu_device *rp; 

25 if ( (getminor(dev) » 3) > mtu_cnt> { /* if dev doesn't exist */ 

26 return (ENXIO) ; /* then return error condition */ 

27 } /* endif */ 
28 

29 dp - &mtu_tbl[getminor(dev)] ; /* get logical device struct */ 

30 if (dp->mtu_flag & MTU__BDSY) !- 0) { /* if device is in use, */ 

31 return (EBUSY) ; /* return busy status */ 

32 } /* endif */ 
33 

34 dp->mtu__f lag » MTU_BUSY; /* mark device in use & clear flags */ 

35 rp » xx_addr [getminor(dev) » 3] ; /* get device regs */ 

36 oldlevel2 - splhi(>; 

37 while ( (rp~>status £ MTU_LOAD) — 0) { /* while tape not loaded */ 

38 /* display mount request on console */ 

39 cmn__err(CE_NOTE, "ITape MOUNT, drive %d-, minor (dev) & 0x3); 

40 dp->mtu_flag |- MTU__WAIT; indicate process suspended */ 

41 dp->n\tu_to__id - timeout (wakeup, dp, 5*60*HZ) ; /* wait 5 min */ 

42 if (sleep (dp, (PCATCH I PZERO+2) ) — l){/*wait on tape load */ 

43 /* if user aborts process, release */ 

44 dp->mtu_flag - 0; /* tape device by clearing flags */ 

45 untimeout (dp->mtu_tO__id> ; 

46 splx (oldlevel2 ) ; 

47 } /* endif */ 

48 } /* endwhile */ 

49 splx(oldlevel2); 

50 ) /* end mtu__open */ 

51 mtu_int (cntr) 

52 int cntr; /* controller that caused the interrupt */ 

53 { 

54 register struct mtu__device *rp - xx_addr [cntr] ; /* get device regs */ 

55 register struct mtu *dp - fimtu_tbl [cntr « 3 I (rp->status & 0x3)]; 

56 if ( (dp->mtu_f lag & MTU__WAIT) !- 0) { /* if process is suspended */ 

57 /* waiting for tape mount, */ 

58 untimeout (dp->mtu__to__id) ; /* cancel timeout request */ 
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59 dp->flag fc- ~MTUJ«AIT; /* clear wait flag */ 

60 wakeupCdp); /* awaken suspended process */ 

61 } /* endif */ 
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NAME 

ureadc - add character to a uio structure 

SYNOPSIS 

♦include <sys/uio.h> 

int ureadc (int c, uio__t *uioj)) ; 
ARGUMENTS 

c The character added to the uio structure. 

*uioj) Pointer to the uio(D4DK) structure. 
DESCRIPTION 

ureadc transfers the character c into the address space of the uio structure 
pointed to by uio_p, and updates the uio structure as for uiomove(D3DK). 

RETURN VALUE 

0 is returned on success and EFAULT on failure. 

LEVEL 

Base or Interrupt 
SEE ALSO 

uiomove(D3DK), uwritec(D3DK), iovec(D4DK), uio(D4DK) 
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NAME 

useracc - verify whether user has access to memory 

SYNOPSIS 

♦include <sys /types .h> 
♦include <sys/buf .h> 

int useracc (caddr_t base, uint count, int access) ; 

ARGUMENTS 

base The start address of the user data area 

count The size of the data transfer in bytes 

access A flag to determine whether the access is a read or write. The defined 
constant B_READ specifies a read from the device and a write to 
memory. This requires that the user have write access permission for 
the specified data area. The defined constant B_WRITE specifies a 
read from memory and a write to the device. It requires read access 
permission for the data area. (B_READ and B_WRITE are defined in 
the system header file sys/buf .h.) 

DESCRIPTION 

useracc verifies if a user has proper access to memory. It is not necessary to 
use useracc for buffered I/O (including use of the copyin(D3DK) and 
copyout(D3DK) functions). 

RETURN VALUE 

Under normal conditions, 1 is returned. If the user does not have the proper 
access permission to the memory specified return EFAULT. 

LEVEL 

Base Only (Do not call from an interrupt routine) 

SEE ALSO 

drv_priv(D3DK) 
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NAME 

uwritec - remove a character from a uio structure 

SYNOPSIS 

♦include <sys/uio.h> 

int uwritec (uio_t *uioj)) ; 

ARGUMENTS 

*uio_p Pointer to the uio(D4DK) structure. 

DESCRIPTION 

uwritec returns a character from the uio structure pointed to by uioj), and 
updates the uio structure as for uiomove(D3DK). 

RETURN VALUE 

The next character for processing is returned on success, and -1 is returned if 
uio is empty or there is an error. 

LEVEL 

Base or Interrupt 
SEE ALSO 

uiomove(D3DK), ureadc(D3DK), iovec(D4DK), uio(D4DK) 
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NAME 

vtop - convert virtual to physical address 

SYNOPSIS 

♦include <sys/types .h> 

paddr_t vtop (long z^fl^i^ir, proc_t *p) ; 

ARGUMENTS 

vaddr Virtual address to convert. 

p Pointer to the proc(D4X) structure used by vtop to locate the infor- 

mation tables used for memory management. To indicate that the 
address is in kernel virtual space or in the virtual space of the current 
process, set p to NULL. Block drivers that can transfer data directly in 
and out of user memory space must set p to the b_proc member of 
the buf (D4DK) structure. 

DESCRIPTION 

vtop converts a virtual address to a physical address. When a driver receives a 
memory address from the kernel, that address is virtual. Generally, memory 
management is performed by the MMU. However, devices that access memory 
directly (DMA) deal only with physical memory addresses. In such cases, the 
driver must provide the device with physical memory addresses. 

The virtual address is the memory address being translated. The vtop function 
returns the translated address. 

The same functionality is provided by the kvtophys(D3D) function. 
RETURN VALUE 

Under normal conditions, a physical address is returned. Otherwise, the follow- 
ing can be returned: 

-1 if the virtual address to be translated is not a valid one 

0 if there is no physical memory mapped to the virtual address 

LEVEL 

Base or Interrupt. 
SEE ALSO 

BCI Driver Development Guide, Chapter 6, "Input/Output Operations" 
btop(D3DK), btopr(D3DK), ptob(D3DK), kvtophys(D3D) 
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NAME 

wakeup ~ resume suspended process execution 

SYNOPSIS 

♦include <sys/types.h> 

void juakeup {caddr JL event) ; 
ARGUMENT 

event Address that is the same address used by sleep(D3DK) to suspend 
process execution. 

DESCRIPTION 

wakeup awakens all processes that called sleep with an address as the event 
argument. This lets the processes execute according to the scheduler. Ensure 
that the same et;ienf argument is used for both sleep and wakeup. It is recom- 
mended for code readability and for efficiency to have a one-to-one correspon- 
dence between events and sleep addresses. Also, there is usually one bit in the 
driver flag member that corresponds to the reason for calling sleep. 

Whenever a driver calls sleep, it should test to ensure the event on which the 
driver called sleep occurred. There is an interval between the time the process 
that called sleep is awakened and the time it resumes execution where the state 
forcing the sleep may have been reentered. This can occur because all 
processes waiting for an event are awakened at the same time. The first process 
given control by the scheduler usually gains control of the event. All other 
processes awakened should recognize that they cannot continue and should reis- 
sue sleep. 

RETURN VALUE 

None 

LEVEL 

Base or Interrupt 
SEE ALSO 

BCI Driver Development Guide, Chapter 10, "Synchronizing Hardware and 
Software Events" 

delay(D3DK), biodone(D3DK), biowait(D3DK), sleep(D3DK), 
tixneout(D3DK), untimeout(D3DK) 

EXAMPLE 

See the untiineout(D3DK) function page for an example of wakeup. 
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NAME 

WR - get pointer to the write queue for this module or driver 

SYNOPSIS 

tinclude <sys/stream.h> 
♦include <sys/ddi.h> 

queue_t WR(queue_t ; 
ARGUMENTS 

(f Pointer to the read queue whose write queue is to be returned. 

DESCRIPTION 

The WR function accepts a read queue pointer as an argument and returns a 
pointer to the zmte queue of the same module. 

CAUTION: Make sure the argument to this function is a pointer to a read queue. 
WR will not check for queue type, and a system panic could result if the pointer is 
not to a read queue. 

RETURN VALUE 

The pointer to the write queue. 

LEVEL 

Base or Interrupt 

SEE ALSO 

STREAMS Programmer's Guide 

0THERQ(D3DK), RD(D3DK) 
EXAMPLE 

In a STREAMS close routine, the driver or module is passed a pointer to the 
read queue. The driver must zero out the c^ptr field of both the read and write 
queues if it had previously initialized them in its open routine. These usually 
are set to the address of the module-specific data structure for the minor device. 

1 xxxclose(q, flag) 

2 queue__t *q; 

3 Int flag; 

4 { 

5 q->q_ptr - NULL; 

6 WR(q)->q_j>tr - NULL; 

7 } 
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This chapter describes the data structures used by drivers to share information 
between the driver and the kernel. All driver data structures shared by both 
DDI and DKI are identified with the (D4DK) cross reference code. All DDI-only 
or DKI-only structures are identified with the (D4D) or (D4K) cross reference 
codes respectively. 

In this section, reference pages contain the following headings: 

■ NAME summarizes the structure's purpose. 

■ SYNOPSIS lists the include file that defines the structure. 

■ DESCRIPTION provides general information about the structure. 

■ STRUCTURE MEMBERS lists all accessible structure members. 

■ SEE ALSO gives sources for further information. 

Table 4-1 summarizes the STREAMS structures described in this section. 
STREAMS structures may be used in either DDI or DKI. 



Table 4-1 : STREAMS Data Structure Summary 



Routine 


Description 


datab 


STREAMS message data structure 


free_rtn 


structure specifying routine that frees non-STREAMS data 
buffers 


nodule_info 


STREAMS driver identification and limit value structure 


msgb 


STREAMS message block structure 


qband 


STREAMS queue flow control information structure 


qinit 


structure specifying STREAMS queue processing procedures 


queue 


STREAMS queue structure 


streamtab 


structure specifying qinit structures 
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Table 4-2 summarizes structures that are not specific to STREAMS I/O. These 
structures may be used in either DDI or DKI, except as noted. 



Table 4-2: Data Structures not Specific to STREAMS 



Routine 


Description 


Type 


buf 


block I/O data transfer structure 




cred 


access credential structure 




hdedata 


hard disk error data structure 


DDI only 


iovec 


structure specifying address and size of 
I/O request using uio(D4DK) 




map 


private memory map structure 




uio 


scatter/gather 1/ O request structure 





Do not declare arrays of structures as the size of the structures may 
change between releases. Rely only on the structure members listed in 
this chapter and not on unlisted members or the position of a member in 
a structure. 
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NAME 

buf - block I/O data transfer structure 

SYNOPSIS 

♦include <sys/buf .h> 

DESCRIPTION 

The buf structure is the basic data structure for block I/O transfers. Each block 
I/O transfer has an associated buffer header. The header contains all the buffer 
control and status information. For drivers, the buffer header pointer is the sole 
argument to a block driver strategy(D2DK) routine. Do not depend on the size 
of the buf structure when writing a driver. 

It is important to note that a buffer header may be linked in multiple lists simul- 
taneously. Because of this, most of the members in the buffer header cannot be 
changed by the driver, even when the buffer header is in one of the drivers' work 
lists. 

Buffer headers are also used by the system for unbuffered or physical I/O for 
block drivers. In this case, the buffer describes a portion of user data space that 
is locked into memory (see physiock(D3D)). 

Block drivers often chain block requests so that overall throughput for the device 
is maximized. The av_forw and the av_back members of the buf structure 
can serve as link pointers for chaining block requests. 

The following figure illustrates two linked lists of buffers. The top illustration is 
the bfreelist, the list of available buffers. The bottom illustration is a queue of 
allocated buffers. The lined areas indicate other buffer members. 



bfreelist 



buf structures 



av_forw 




av_forw 




av_forw 






av_back 


av back 


av back 






wm. 



Available Buffers 




Allocated Buffers 

STRUCTURE MEMBERS 
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int 




/ 


OUXXtSx 9weil»UB / 


at met buf 


*b forw/ 




liAadAd bv d tab of eonf e */ 


stimct buf 


*b back- 




bAAddd bv d tab of eonf .e */ 


at met feuf 


*av forw/ 


/* 


DT*iv«T" worV liat linlt */ 

VXXW4a IIVXI^ XXfiVW XXIilJV / 


3 timet iDUf 


*av bade ; 




Driver vork lists link */ 


o dev t 


b dev/ 


/ 


Ma 3 or /minor device numbers */ 


im a 1 evntkti 




/* 


Af V%t/t*An ti*annfAi" A/ 

V ox 0jfC9B viV CxflitiBXtSx / 


eaddr t 


b addr; 


/ 


Buff #41"' a viT"ti3al addreaa */ 

0UlXXwX O VXXwUAX QHVIiXJlX ^ O fip / 


d&ddr t 


b blkno* 


/ 


Bloelc number on deviee */ 




b oerror# 


/* 


Old ooat— T/O error nuniber */ 


unsigned int 


b_resid; 


/* 


# of bytes not transferred 


clocJc_t 


b_start; 


/* 


request start time */ 


struct proc 


*bjproc; 


/* 


Process table entry address */ 


struct page 


*b_pages; 


/* 


page list for PAGEIO */ 


unsigned long 


b_reltime; 


/* 


previous release time */ 


long 


b_bufsize; 


/* 


size of allocated buffer */ 


int 


(*b_iodone) ; 


/* 


function called by biodone */ 


struct vnode 


*b_vp; 


/* 


vnode associated with block */ 


int 


b_error; 


/* 


expanded error field */ 


dev__t 


b__edev; 


/* 


expanded dev field */ 



CAUTION: Buffers are a shared resource within the kernel. Drivers should read 
or write only the members listed in this section. Drivers that attempt to use 
undocumented members of the buf structure risk corrupting data in the kernel 
or on the device. 

The paddr macro (defined in buf .h) provides access to the b__un.b_addr 
member of the buf structure. (b__un is a imion that contains b_addr.) 

The members of the buffer header available to test or set by a driver are as fol- 
lows: 

b__f lags stores the buffer status and tells the driver whether to read or write to 
the device. The driver must never clear the b_f lags member. If this is done, 
unpredictable results can occur including loss of disk sanity and the possible 
failure of other kernel processes. 

Valid flags are as follows: 

B__BUSY indicates the buffer is in use. 

B__DONE indicates the data transfer has completed. 

B_ERROR indicates an I/O transfer error. 

B__KERNBUF indicates the buffer is allocated by the kernel and not by a 
driver. 

B_PAGEIO indicates the buffer is being used in a paged I/O request. 

If B_PAGEIO is set, the b_pages field of the buffer 
header will point to a sorted list of page structures. Also, 
the b_addr field of the buffer header will be offset into 
the first page pf the page list. If B_PAGEIO is not set, the 
b_addr field of the buffer header will contain the kernel 
virtual address of the I/O request. The b_pages field of 
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the buffer header is not used. 



B PHYS 



indicates the buffer header is being used for physical 
(direct) I/O to a user data area. The b_un member con- 
tains the starting address of the user data area. 



B READ 



indicates data is to be read from the peripheral device into 
main memory. 



B WANTED 



indicates the buffer is sought for allocation. 



B WRITE 



indicates the data is to be transferred from main memory 
to the peripheral device. B_WRITE is a pseudo flag that 
occupies the same bit location as B_READ. BJWRITE can- 
not be directly tested; it is only detected as the NOT form 
of B READ. 



av_f orw and av_back can be used by the driver to link the buffer into driver 
work lists. 

b_dev contains the external major and minor device nim\bers of the device 
accessed. For Release 4.0, this field is replaced by the expanded device number 
field b__edev. b_dev is maintained for compatibility. 

b_bcount specifies the number of bytes to be transferred in both a paged and a 
non-paged I/O request. 

b_addr is either the virtual address of the I/O request, or an offset into the first 
page of a page list depending on whether B_PAGEIO is set. If it is set, the 
b_j>ages field of the buffer header will point to a sorted list of page structures 
and b_addr will be the offset into the first page. If BJPAGEIO is not set, 
b__addr is the virtual address from which data is read or to which data is writ- 
ten. 

bjblkno identifies which logical block on the device (the device is defined by the 
device number) is to be accessed. The driver may have to convert this logical 
block number to a physical location such as a cylinder, track, and sector of a disk. 

The b__oerror with a char data type and the expanded b_error with an int 
data type both may hold an error code that should be passed as a return code 
from your driver routine. b_error and b__oerror is set in conjunction with 
the B__ERROR flag (set by the operating system in the b_f lags member). The 
error codes are described in Appendix A. 

b_resid indicates the number of bytes not transferred because of an error. 
b_start holds the time the I/O request was started. 

b_proc contains the process table entry address for the process requesting an 
unbuffered (direct) data transfer to a user data area (this member is set to 0 
when the transfer is buffered). The process table entry is used to perform proper 
virtual to physical address translation of the b_un member. 

b_pages contains a pointer to the page structure list used in a paged I/O 
operation. 
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b_buf size contains the size of the allocated buffer. 

(*b_iodone) identifies a specific biodone routine to be called by the driver 
when the I/O is complete. 

b_vp identifies the vnode associated with the block. 
SEE ALSO 

strategy(D2DK), physiock(D3D), brelse(D3DK), clrbuf(D3DK), 
iovec(D4DK), uio(D4DK) 
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NAME 

cred - access credential structure 

SYNOPSIS 

♦include <sys/cred.h> 

DESCRIPTION 

This structure is used to check the access credentials of the process requesting 
access to kernel space. 

The size of the cr_groups [ ] array is configurable, however, its size is the same 
for all cred structures. Note that cr_ngroups records the number of elements 
currently in use, not the array size. 

STRUCTURE MEMBERS 



ushort 


cr_ref ; 


/* 
/* 


reference count on processes using */ 
cred structure. Not set by drivers. */ 


ushort 


cr_ngroups; 


/* 


number of groups in cr_groups */ 


uid_t 


cr_uid; 


/* 


effective user ID */ 


gid_t 


cr^gid; 


/* 


effective group ID */ 


uid_t 


cr^^ruid; 


/* 


real user ID */ 


gid_t 


cr^rgid; 


/* 


real group ID */ 


uid_t 


cr_suid; 


/* 


"saved" user ID (from exec) */ 


gidit 


cr_sgid; 


/* 


"saved" group ID (from exec) */ 


gid_t 


cr_groups[l] ; 


/* 


supplementary groups list */ 



The cred structure is defined as type credit. 
SEE ALSO 

open(D2DK), close(D2DK), ioctl(D2DK), nimap(D2DK), read(D2DK), 
write(D2DK), segxnap(D2DK) 
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NAME 

datab - STREAMS message data structure 

SYNOPSIS 

#include <sys/stream.h> 

DESCRIPTION 

The datab structure describes the data of a STREAMS message. The actual data 
contained in a STREAMS message is stored in a data buffer pointed to by this 
structure. A msgb (message block) structure includes a field that points to a 
datab structure. 

A data block can have more than one message block pointing to it at one time, so 
the db_ref member keeps track of a data block's references, preventing it from 
being deallocated until all message blocks are finished with it. 

STRUCTURE MEMBERS 



union { 

struct 

struct 
} db__f; 

unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned int 
caddr_t 
long 



datab 
free rtn 



*freep; 
*frtnp; 

*db_base; 

*db_lim; 

db_ref; 

db_type; 

db__iswhat; 

db_size; 

db_msgaddr; 

db filler; 



/* routine to free non-STREAMS buffer */ 



/* first byte of buffer */ 

/* last byte (+1) of buffer */ 

/* # of message pointers to this data */ 

/* message type */ 

/* status of msg/dat a/buffer triplet */ 
/* used internally */ 

/* triplet mesg header; points to datab */ 
/* reserved for future use */ 



A datab structure is defined as type dblk_t. 
SEE ALSO 

BCI Driver Development Guide, Chapter 4, "Header Files and Data Structures" 
free_rtn(D4DK), msgb(D4DK) 
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NAME 

f ree_rtn - structure that specifies a driver's message freeing routine 

SYNOPSIS 

tinclude <8ys/8tream.h> 

DESCRIPTION 

The f ree_rtn structure is referenced by the dp_f reep n\ember of the datab 
structure. When f reeb(D3D) is called to free the message, the driver's message 
freeing routine (referenced through the f ree_rtn structure) is called, with argu- 
ments, to free the data buffer. 

STRUCTURE MEMBERS 

void (*free_func) 0 /* user's freeing routine */ 
char *free__arg /* arguments to free_func() */ 

The free__rtn structure is defined as t)^ frtn_t. 

SEE ALSO 

datab(D4DK), esballoc(D3DK) 
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NAME 

hdedata - hard disk error data structure 

SYNOPSIS 

♦include <sys/hdelog . h> 

DESCRIPTION 

The hdedata data structure temporarily stores hard disk error information sent 
to an error queue. A hdedata structure is initialized for every disk on the sys- 
tem by hdeeqd(D3D) when the system is booted. An error queue is also initial- 
ized by hdeeqd. 

When the disk driver finds an error, it provides hdelog(D3D) with the error 
information, hdelog passes the hdedata structure for the error to the error 
queue. This error queue is a queue of bad block reports that have not been 
remapped. This queue resides in the kernel and not on the disk. 

After a number or errors are accumulated, an administrator examines the list of 
errors collected in the queue. If any of the errors need to be "fixed," the 
administrator remaps the bad block. Remapping means that the block address is 
rewritten to a defect table on the disk. Physical Description sector information 
points to this defect table. 

The following figure illustrates the logging of hard disk errors: 



driver 




hdelog 




error 






queue 



STRUCTURE MEMBERS 

o_dev_t dislcdev; 

char dskserno [ 12 ] ; 
daddr t blkaddr; 



char 



readtype; 



char severity; 

char badrtcnt; 

char bit width ; 

time_t timestn^; 



hdedata 
structure 



/* Major/minor disk device number */ 

/* (major number for character device) */ 

/* Disk pack serial number (can be all zeros) 

/* Physical block address */ 

/* in machine- independent form */ 

/* Error type:CRC (cyclical redundancy check) 

/* or ECC (error check and correction) */ 

/* Severity type: marginal or unreadable */ 

/* Number of unreadable tries */ 

/* Bitwidth of corrected error: 0 if CRC */ 

/* Time staic^ */ 



NOTE: The disk pack serial number is not currently evaluated, but it must con- 
tain a value. Set to all zeros. 

SEE ALSO 

hdeeqd(D3D), hdelog(D3D) 
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NAME 

iovec - data storage structure for I/O using uio(D4DK) 

SYNOPSIS 

♦include <sys/uio.h> 

DESCRIPTION 

An iovec structure describes a data storage area for transfer in a uio structure. 
Conceptually, it may be thought of as a base address and length specification. 

STRUCTURE MEMBERS 

caddr_t iov_baae; /* base address of the data storage area */ 

/* represented by the iovec structure */ 
int ioy_len; /* size of the data storage area in bytes */ 

SEE ALSO 

uio(D4DK) 
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NAME 

map - private memory map structure 

SYNOPSIS 

♦include <sys/roap.h> 

DESCRIPTION 

The map structure defines the size and index into a private space management 
map. The private map is declared as an instance of the map structure using the 
driver prefix in the form prefixmap. The size is defined in the m_size field as 
the number of arbitrary units used to make up the map. The index is defined in 
m_addr as the first available unit of the map. 

Private maps are managed through a set five functions: 

rmalloc allocates space from a defined and initialized map 
rmf ree returns previously allocated space to map 

rminit defines a map structure and initializes a map table 

mwant returns the number of processes waiting for free space 

rmsetwant increments the count of the number of processes waiting for 
free space in the map 

Private maps can be made up of any units appropriate for the specific uses of the 
map. For example, units may be byte addresses, pages of memory, or blocks. 
The map itself does not define the resource, and the size of the map is not related 
to the size of the map structure. 

STRUCTURE MEMBERS 

unsigned long nrsize /* number of units available */ 
unsigned long m_addr /* address of first available unit */ 

SEE ALSO 

rmalloc(D3DK), rmf ree(D3DK), rminit(D3DK), rmsetwant(D3DK), 
rmwant(D3DK) 
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NAME 

module_inf o - STREAMS driver identification and limit value structure 

SYNOPSIS 

finclude <sys /stream. h> 

DESCRIPTION 

When a module or driver is declared, several identification and limit values can 
be set. These values are stored in the module^iiif o structure. 

The module_info structure is intended to be rdad-only. However, the flow 
control limits (mi__hiwat and mi_lowat) and the packet size limits (mi__minpsz 
and mi_maxpsz) are copied to the QUEUE structure, where they may be 
modified. 

STRUCTURE MEMBERS 

ushort mi_idnum 
char 
short 
short 
ushort 
ushort 



*mi_idnaiiie; 
mi_minpsz; 
mi^maxpsz; 
mi_hiwat ; 
mi lowat; 



/* module ID number */ 
/* module name */ 
/* minimum packet size */ 
/* maximum packet size */ 
/* high water mark */ 
/* low water mark */ 



The constant FMNAMESZ, limiting the length of a module's name, is currently set 
to a value of eight. 

SEE ALSO 

queue(D4DK) 
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NAME 

xnsgb - STREAMS message block structure 

SYNOPSIS 

♦include <sys/stream.h> 

DESCRIPTION 

A STREAMS message is made up of one or more message blocks, referenced by a 
pointer to a msgb structure. The b_next and b_prev pointers are used to link 
messages together on a QUEUE'S message queue. The b_cont pointer links mes- 
sage blocks together when a message is composed of more than one block. 

Each msgb structure also includes a pointer to a datab structure, the data block 
(which contains pointers to the actual data of the message), and the type of the 
message. 



STRUCTURE MEMBERS 

struct msgb *b_next; /* 

struct msgb *b_prev; /* 

struct msgb *b_cont; /* 

unsigned char *b_rptr; /* 

unsigned char *b_wptr; /* 

struct datab *b_datap; /* 

unsigned char b_band; /* 

unsigned char b_padl; /* 

unsigned short b_flag; /* 

long b__pad2; /* 



next message on queue */ 
previous message on queue */ 
next message block 
1st unread data byte of buffer */ 
1st unwritten data byte of buffer */ 
pointer to data block */ 
message priority */ 
used internally */ 
used by stream head */ 
used internally */ 



b_j>ad2; 

The msgb structure is defined as type xriblk_t. 
SEE ALSO 

BCI Driver Development Guide, Chapter 4, "Header Files and Data Structures' 
datab(D4DK) 
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NAME 

qband - STREAMS queue flow control information structure 

SYNOPSIS 

♦include <sys/stream.h> 

DESCRIPTION 

The qband structure contains flow control information for each priority band in 
a queue. 

The qband structure is defined as type qband_t. 

STRUCTURE MEMBERS 

struct qband *qb_next; /* next band's info */ 



ulong qb__count /* number of bytes in band */ 

struct msgb *qb_first; /* start of band's data */ 

struct msgb *qb_last; /* end of band's data */ 

ulong *qb__hiwat; /* band's high water mark */ 

ulong *qb_lowat; /* band's low water mark */ 

ulong *qb_flag; /* band's status */ 

long *qb_j>adl; /* reserved for future use */ 



SEE ALSO 

msgb(D4DK), queue(D4DK) 
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NAME 

qinit - STREAMS queue processing procedures structure 

SYNOPSIS 

tinclude <sys/streain.h> 

DESCRIPTION 

The qinit structure contains pointers to processing procedures for a QUEUE. 
The streamtab structure for the module or driver contains pointers to one 
qinit structure for both upstream and downstream processing. 

STRUCTURE MEMBERS 



int (*qi_J>utp) 0 ; /* put procedure */ 

int (*qi_srvp) () ; /* service procedure */ 

int (*qi_qopen) () ; /* open procedure */ 

int (*qi_qclose) () ; /* close procedure */ 

int (*qi_qadmin) () ; /* unused */ 



struct module_in£o *qi_minfo; /* module parameters */ 

struct module_stat *qi_mstat; /* module statistics */ 

SEE ALSO 

BCI Driver Development Guide, Chapter 4, "Header Files and Data Structures' 
queue(D4DK), streamtab(D4DK) 
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NAME 

queue - STREAMS queue structure 

SYNOPSIS 

♦include <sys/stream.h> 

DESCRIPTION 

A STREAMS driver or module consists of two queue structures, one for 
upstream processing (read) and one for downstream processing (write). This 
structure is the major building block of a stream. It contains pointers to the pro- 
cessing procedures, pointers to the next and previous queues in the stream, flow 
control parameters, and a pointer defining the position of its messages on the 
STREAMS scheduler list. 

The queue structure is defined as t5rpe queue_t. 
STRUCTURE MEMBERS 



struct qinit 


*q_qinfo; 


/* 


module or driver entry points */ 


struct msgb 


*q_first; 


/* 


first message in queue */ 


struct msgb 


*q_last ; 


/* 


last message in queue */ 


struct queue 


*CL.next; 


/* 


next queue in stream */ 


struct queue 


*q__linlc; 


/* 


used internally */ 


_V0ID 


<U>tr; 


/* 


pointer to private data structure */ 


ulong 


q_count; 


/* 


approximate size of message queue */ 


ulong 


cLflag; 


/* 


status of queue */ 


long 


q^minpsiz; 


/* 


smallest packet accepted by QUEUE */ 


long 


qjnaxpsiz; 


/* 


largest packet accepted by QUEUE */ 


ulong 


q__hiwat; 


/* 


high water mark */ 


ulong 


q_lowat ; 


/* 


low water mark */ 


struct qband 


*q_bandp; 


/* 


separate flow info */ 


unsigned char 


q_nband; 


/* 


number of priority band > 0 */ 


unsigned char 


cLJ>adl[3]; 


/* 


reserved for future use */ 


long 


qjPad2[2]; 


/* 


reserved for future use */ 



SEE ALSO 

msgb(D4DK), qband(D4DK) 
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NAME 

streamtab - STREAMS entity declaration structure 

SYNOPSIS 

tinclude <sys/stream.h> 

DESCRIPTION 

Each STREAMS driver or module must have a streamtab structure. Drivers 
access this structure through the cdevsw table, and modules use the fmodsw 
table. 

streamtab is made up of qinit structures for both the read and write queue 
portions of each module or driver. (Multiplexing drivers require both upper and 
lower qinit structures.) The qinit structure contains the entry points through 
which the module or driver routines are called. 

Normally, the read QUEUE contains the open and close routines. Both the 
read and write queue can contain put and service procedures. 

STRUCTURE MEMBERS 

struct qinit *st_rdinit; /* read QUEUE */ 

struct qinit *st_wrinit; /* write QUEUE */ 

struct qinit *stjMQxrinit ; /* lower read QUEUE*/ 

struct qinit *st_muxwinit; /* lower write QUEUE*/ 

SEE ALSO 

qinit(D4DK) 
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NAME 

uio - scatter/gather I/O request structure 

SYNOPSIS 

♦include <sys/uio.h> 

DESCRIPTION 

A uio structure describes an I/O request that can be broken up into different 
data storage areas (scatter /gather I/O). A request is a list of iovec structures 
(base/length pairs) indicating where in user space or kernel space the I/O data is 
to be read/written. 

The contents of uio structures passed to the driver through the entry points 
should not be written by the driver. The uioinove(D3D) function takes care of 
all overhead related to maintaining the state of the uio structure. 

STRUCTURE MEMBERS 

iovec_t *uio_iov; pointer to the start of the iovec */ 

/* list for the uio structure */ 
int uio^iovcnt; /* the number of iovecs in the list */ 

off_t uio_offset; /* offset into file where data is */ 

/* transferred from or to */ 
short uio_segflg; /* identifies the type of I/O transfer: */ 

/* UIO^SYSSPACE: kernel <-> kernel */ 

/* UI0_USBRSPACE: kernel <-> user */ 
short uio__fmode; /* file mode flags (not driver setable) */ 
daddr_t uio_limit; /* ulimit for file (maximum block offset) . */ 

/* not driver setable */ 
int uio_resid; /* residual count */ 

The uio__iov member is a pointer to the beginning of the iovec(D4DK) list for 
the uio. When the uio structure is passed to the driver through an entry point, 
the driver should not set uio__iov. When the uio structure is created by the 
driver, uio_iov should be initialized by the driver and not written to afterward. 

SEE ALSO 

iovec(D4DK) 
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Appendix A: Error Codes 



This appendix lists the error codes that should be returned by a driver routine 
when an error is encountered. Table A-1 lists the error values in alphabetic 
order. All the error values are defined in /usr/include/sys/errno.h. In the 
driver open(D2D), close(D2D), ioctl(D2D), read(D2D), and write(D2D) rou- 
tines, errors are passed back to the user with the return instruction at the end 
of the routine. In the driver strategy(D2D) routine, errors are passed back to 
the user by setting the bjerror member of the buf (D4D) structure to the error 
codes. 

For STREAMS ioctl routines, error numbers translate to the error numbers sent 
upstream in an M_IOCNAK message. For STREAMS read and write routines, 
error numbers translate to the error numbers sent upstream in an MJIRROR mes- 
sage. 



NOTE 



The driver print routine should not return an error code, as the function that 
it calls, cnttijerr(D3D), is declared as void (no error is returned). 



Table A-1 : Driver Error Codes 



Error 
Value 


Error Description 


Use in these 

Driver Routines (D2D) 


EAGAIN 


Kernel resources, such as the buf struc- 
ture or cache memory, are not available 
at this time; cannot open device (device 
may be busy, or the system resource is 
not available). 


open, ioctl, read, 
write, strategy 


EFAULT 


An invalid address has been passed as 
an argument; memory addressing 
error. 


open, close, ioctl, 
read, write, stra- 
tegy 


EINTR 


PCATCH set, wake with signal; sleep 
interrupted by signal. 


open, close, ioctl, 
read, write, stra- 
tegy 


EINVAL 


An invalid argument was passed to the 
routine. 


open, ioctl, read, 
write, strategy 
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Table A-1 : Driver Error Codes (continued ) 



EIO 


A device error occurred; a problem 
was detected in a device status register 
(the I/O request was valid, but an 
error occurred on the device). 


open, 
read, 
tegy 


close, 
write. 


ioctl, 
stra- 


ENXIO 


An attempt was made to access a dev- 
ice or subdevice that does not exist 
(one that is not configured); an attempt 
was made to perform an invalid I/O 
operation; an incorrect minor number 
was specified. 


open, 
read, 
tegy 


close, 
write. 


ioctl, 
stra- 


EPERM 


A process attempting an operation did 
not have required permission. 


open, 
write 


ioctl, 
f close 


read. 


EROFS 


An attempt was made to open for writ- 
ing a read-only device. 


open 



Table A-2 cross references error values to the driver routines from which the 
error values can be returned. 



Table A-2: Error Codes by Driver Routine 



open 


close 


ioctl 


read, write, 
and strategy 


EAGAIN 


EFAULT 


EAGAIN 


EAGAIN 


EFAULT 


EINTR 


EFAULT 


EFAULT 


EINTR 


EIO 


EINTR 


EINTR 


EINVAL 


ENXIO 


EINVAL 


EINVAL 


EIO 




EIO 


EIO 


ENXIO 




ENXIO 


ENXIO 


EPERM 




EPERM 




EROFS 
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Appendix B: Migration from Release 3.2 to 
Reiease 4.0 

The UNIX System V Block and Character Interface (BCD Reference Manual defined 
the functions, routines, and structures appropriate for use in the UNIX System V 
Release 3.2 environment. Table B-1 presents all of the kernel utility functions 
included in the BCI followed by information about changes to the functions for 
Release 4.0. Most of the functions fall into one of these categories: 

■ No change. The function behaves the same way it did in BCI. 

■ Not supported. The function is not included in either DDI or DKI. No 
replacement is provided. 

■ Supported but obsolete. The function is included in DDI or DKI but a 
replacement is suggested. 

■ Macro reimplemented as function. The calling and return s)mtax has not 
changed for macros converted to functions. 

■ Replaced. The function is not included in either DDI or DKI but a 
replacement is provided. 

■ Renamed only. The function was renamed, but the functionality is the 
same as it was under the old name. 
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Table B-1: 3.2 to 4.0 Migration 



BCI 


Comments 


DDI/DKI 


adjmsg 


No change 


adjmsg 


allocb 


For memory mapped I/O, use esbal- 


allocb 




loc 




backq 


No change 


backq 


bcopy 


No change 


bcopy 


brelse 


Supported but obsolete. Allocate 


kmem_free 




buffer with kinem_alloc or 


or f reerbuf 




getrbuf(D3DK). 




btoc 


Replaced 


btop, btopr 


bufcall 


Do not use with esballoc 


bufcall 


bzero 


Word alignment no longer required 


bzero 


canon 


Not supported 


None 


canput 


Use bcanput to test specific priority 


canput 




band 




clrbuf 


buf structure has changed 


clrbuf 


cmn_err 


No change 


cmn__err 


copyb 


No change 


copyb 


GOpyin 


Supported but obsolete. Use uiomove 


uiomove 


copymsg 


No change 


copymsg 


copyout 


Supported but obsolete. Use uiomove 


uiomove 


ctob 


Replaced 


ptob 


datamsg 


No change 


datamsg 


delay 


No change 


delay 


dina__alloc 


Not supported 


None 


dma^breakup 


Replaced 


dma_pageio 


drv__rfile 


Not supported 


None 


dupb 


No change 


dupb 


dupmsg 


No change 


dupmsg 


enableok 


Macro reimplemented as function 


enableok 


flushq 


Use f lushband to flush specific prior- 


flushq 




ity band 
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Table B-1 : 3.2 to 4.0 Migration (continued ) 



BCI 


Comments 


DDI/DKI 


freeb 


Frees allocb and esballoc allocated 


freeb 




buffers 




freemsg 


No change 


freemsg 


fubyte 


Replaced 


uicinove 


fuword 


Replaced 


uicmove 


getc 


Not supported 


None 


getcb 


Not supported 


None 


getcf 


Not supported 


None 


geteblk 


Replaced. Use kmem alloc or getrbuf 


kmem alloc 




to allocate a buffer header 


or getrbuf 










No rhan<>"P 

X ^ V/ V.X LUX L £LV> 


CTPf" VPP 




1 N \_/ V.X ICil ^f-J^ 




hripl OCT 


No rHpinp"P 

X X \^ Vx tcu i-)^^ 


hirlpl OCT 


i.nb 




None 


ind 


Not supported 


None 


insq 


No chanee 


insq 


icxione 


Renamed only 


biodone 


iomove 


Replaced 


uicmove 


iowait 


Renamed only 


bicwait 


kseg 


Not supported 


None 


XinKD 


No change 


iinJcjD 


logmsg 


Not supported 


None 


logs tray 


Not supported 


None 


longjmp 


Not supported 


None 


major 


Renamed. Macro reimplemented as 


getmajcr 




function 




nakedev 


Renamed. Macro reimplemented as 


makedevice 




function 




malice 


Renamed only 


rmalloc 


mapinit 


Renamed only 


rminit 


mapwant 


Renanried only 


rmsetwant 
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Tabie B-1 : 3.2 to 4.0 Migration (continued ) 



BQ 


ComnriGnts 


DDI/DKI 


max 


No change 


max 


mfree 


Renanned only 


rmfree 


mln 


iNO cnange 


min 


iiu.no J. 


j\enajTi6Q* jviacro reinripienienieci as 


geuminoj. 




lunction 




msgdsize 


No change 


msgdsize 


noenable 


Macro reimplemented as function 


noenable 


OTHERQ 


Macro reimplemented as function 


OTHERQ 


physck 


Replaced. Functionality included in 


physiock 




physiock 




physio 


Replaced. Functionality included in 


physiock 




physiock 




psignal 


Not supported 


None 


pullupnsg 


No change 


pullupmsg 


putbq 


No change 


putbq 


putc 


Not supported 


None 


putcb 


Not supported 


None 


putcf 


Not supported 


XT _ 

None 


putctl 


No change 


putctl 


putctll 


No change 


putctll 


putnext 


Macro reimplemented as function 


putnext 


putq 


No change 


putq 


qenable 


Macro reimplemented as function 


qenable 


qreply 


No change ^ 


qreply 


qsize 


No change 


qsize 


RD 


Macro reimplemented as function 


RD 


rmvb 


No change 


mvb 


rmvq 


No change 


mvq 


signal 


Not supported 


None 


sleep 


No change 


sleep 


spl 


No change 


spl 
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Table B-1 : 3.2 to 4.0 Migration (continued ) 



BQ 


Comments 


DDI/DKI 


spix 


J. ^ W \,X 1.CU i-fm^ 


spj.x 




Mnf QiinTvirfprl 




W kp/ \^ 




VmPTTTl "Ftpp 






of" r*! ryrt 

O L« JL J_W^ 






11 i oinnve 


sus6ir 


Rpnlaced 


dxv piriv 


suword 


Rpnlarpd 




testb 


NTo r}ianp"P 


testb 


W> 1 Vii/ Ul W» 


^To rViPi'np'P 


L. XI I RS UL 




NTof <ii iTinorf pH 


None 


ttin 


Not siinDortpd 


None 


ttinit 


NTot mmnortpd 


None 


tt i ocom 


NFot <*iir>r>nri"pH 


None 




^Tnf QiTn'oorfpH 


N^onp 




iN'Ul £>U.LIL/\J1 lxz\X 


iNUllv, 


ttout 


^Fof QiiTiTJorfpH 

INVyl 9U.L/LAJX tCVl 


Nnnp 


t tread 


Not siiDDortpd 


None 




NFof mi"nr>nrfpd 


None 


tttimeo 


Not supported 


None 


tt write 


Not supported 


None 


ttyflush 


Not supported 


None 


ttywait 


Not supported 


None 


ttxput 


Not supported 


None 


unkseg 


Not supported 


None 


unlinkb 


No change 


unlinkb 


untiroeout 


No change 


untimeout 


useracc 


No change 


useracc 


vtop 


No change 


vtop 


wakeup 


No change 


wakeup 


WR 


Macro reimplemented as function 


WR 
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close(D2DK) 2: 6 
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copyb(D3DK) 3:30 
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example 3: 33 
copyout(D3DK) 3: 35 

example 3:35 
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4: 10 
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datab(D4DK) 3:8,48, 4:8 
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example 3: 37 
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driver entry point routines 2: 1-3 
error codes A: 1-2 
kernel functions. 3: 1-6 
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example 3: 38 
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DKI (Driver- Kernel Interface) (see 

DDI/DKI) 
DMA (Direct Memory Access) 3: 40 
dina_pageio(D3D) 3: 40 

example 3: 40 
driver 

block 3: 4-6 

entry points 2: 1-3 

functions 3: 1-6 

porting 1 : 2 

STREAMS 3:2-3 

structures 4: 1-2 
Driver- Kernel Interface (see 

DDI/DKI) 
drv_getpann(D3DK) 3: 42 
drv_hztousec(D3DK) 3: 44 
drv_j)riv(D3DK) 3: 45 
drv__usectohz(D3DK) 3: 46 
drv_usecwait(D3DK) 3: 47 
dupb(D3DK) 3: 48 

example 3: 49 
dupmsg<D3DK) 3: 50 

example 3: 30 

E 

ECC (Error Check or Correction) 
4: 10 

enableok(D3DK) 3: 51 

example 3: 51 
Error Check or Correction (ECC) 
4: 10 

esballoc(D3DK) 3: 52 
esbbcall(D3DK) 3: 53 
etoina jor(D3D) 3: 54 
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f lushband(D3DK) 3: 55 
flushq(D3DK) 3:56 

example 3: 56, 106 
f reeb(D3DK) 3: 58 

example 3:30, 117, 134 
f reemscKD3DK) 3: 59 

example 3: 33, 97, 118 
f reerbuf (D3DK) 3: 60 
f ree_rtn(D4DK) 4: 9 

G 

getema jbr(D3D) 3: 61 
getemindr(D3D) 3: 62 
getma jor(D3DK) 3: 64 

example 3: 64 
getininor(D3DK) 3: 65 

example 3: 28, 38, 40, 71 
getc[(D3DK) 3:66 

example 3: 22, 49, 97 
getrbuf(D3DK) 3: 67 
getvec(D3D) 3:68 

example 3: 68 
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hat_getkpf nuin(D3K) 3: 69 
hdedata(D4D) 4: 10 

example 3: 71, 73 
hdeeqd(D3D) 3: 70, 4: 10 

example 3: 71 
hdelog(D3D) 3: 73, 4: 10 

example 3: 73 
HZ (clock cycles) 3: 38 
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init(D2D) 2: 9 

example 3: 68 
insq(D3DK) 3:76 

example 3: 76 
int(D2D) 2: 10 
ioctl(D2DK) 2: 12 

example 3:35 
iovec(D4DK) 4: 11 
itoeroajor(D3D) 3:78 

K 

kernel, data copy in 3: 12 
kmem_alloG(D3DK) 3: 79 
kniem_f ree(D3DK) 3: 80 
kmem_zallcx:(D3DK) 3: 81 
kvtophys(D3D) 3: 82 

L 

linkb(D3DK) 3: 83 
example 3:8,49 

M 

major device number 3: 54, 78 

external 3: 61 

internal 3: 64 
inakedevice(D3DK) 3: 84 
iTBp(D4D) 4:12 
inax(D3DK) 3: 85 
memory, clear 3: 24 
message block descriptor 3: 48 
message (STREAMS) 3: 8, 1 1, 25 

block 3: 49, 59 



min(D3DK) 3: 86 
minor device number 

external 3:62 

internal 3:65 
irinap(D2K) 2:16 
nKxiule_info(D4DK) 4: 13 
msgb(D4DK) 3: 8, 48, 4: 14 

example 3: 8, 97, 1 06. 1 1 7- 1 1 8 
msgdsize(D3DK) 3: 87 

example 3: 22 

N 

noenable(D3DK) 3:88 

O 

open(D2DK) 2:17 
0THERQ(D3DK) 3:89 
example 3: 89 

P 

page fault 3: 32 
panic 3: 27-28 
physiock(D3DK) 3: 92 

example 3: 40 
pollwakeup(D3DK) 3: 95 
print(D2DK) 2:19 
ptob(D3DK) 3: 96 
pullupmsg(D3DK) 3: 97 

example 3: 97 
putbq(D3DK) 3: 99 

example 3: 22-23, 49, 130 
putctll(D3DK) 3: 102 

example 3: lOO 



index 
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putctl(D3DK) 3: 100 

example 3: 100 
put(D2DK) 2:20 

example 3: 56 
put next (D3DK) 3: 103 

example 3: 8-9. 22-23, 30, 49, 56 
putq(D3DK) 3: 104 

example 3: 37, 76 

Q 

qband(D4DK) 4:15 
qenable(D3DK) 3:105 

example 3: 22-23, 49, 51, 130 
qinit(D4DK) 4:16 
qreply(D3DK) 3: 106 
qsize(D3DK) 3: 108 
queue(D4DK) 4: 17 

example 3: 49, 51, 56, 97, 100, 106, 118 

R 

raw I/O 3: 6 
RD(D3DK) 3: 109 

example 3: 8-9, 56, 106 
read(D2DK) 2:22, 3:35 

example 3: 40 
rnalloc(D3DK) 3:110 

example 3: 112 
nnfree(D3DK) 3:114 
nninit(D3DK) 3:115 
nnsetwant(D3DK) 3: 1 16 

example 3: 112 
rmvb(D3DK) 3:117 

example 3:117 
rmvq(D3DK) 3:118 

examjde 3:118 



nnwant(D3DK) 3: 120 

S 

SAMESTR(D3DK) 3: 121 
scatter/gather I/O 4: 19 
seginap(D2K) 2: 23 
size(D2D) 2: 25 
sleep(D3DK) 3: 122 
spl(D3D) 3: 125 

during DMA 3: 40 
srv(D2DK) 2; 26 

example 3:22,130 
start(D2D) 2:28 
strategy(D2DK) 2: 29, 4: 3 

example 3: 40 
STREAMS entry points 2: 1-3 
STREAMS functions 3:2-3 
STREAMS message blocks 3: 8-9, 48, 
50, 58-59 

STREAMS message queues 3:10-11, 
25, 51 

STREAMS messages 3: 7, 33, 37, 

55-56,87 
STREAMS structures 4: 1-2 
streamtab(D4DK) 4: 18 
strlog(D3DK) 3: 127 
strqget(D3DK) 3: 128 
strqset(D3DK) 3: 129 

T 

testb(D3DK) 3: 130 

example 3: 130 
tiineout(D3DK) 3: 132 

example 3: 22-23, 49, 130, 135 
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uio(D4DK) 4: 19 
uionove(D3DK) 3: 133 
unlin3cb(D3DK) 3:134 

example 3: 134 
untiineout(D3DK) 3: 135 

example 3: 135 
ureadc(D3DK) 3: 138 
useracc(D3DK) 3: 139 
uwritec(D3DK) 3: 140 

V 

vtop(D3D) 3: 141 

w 

wakeup(D3DK) 3: 142 

example 3: 135 
WR(D3DK) 3: 143 

example 3: 143 
write(D2DK) 2: 30, 3: 35 

example 3: 40 
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cred: access credential structure cred(D4DK) 

close: relinquish access to a device * close(D2DK) 

open: gain access to a device open(D2DK) 

start: start access to a device start(D2D) 

useracc: verify whether user has access to memory useracc(D3DK) 

event sleep: suspend process activity pending execution of an sleep(D3DK) 

ureadc: add character to a uio structure ureadc(D3DK) 

vector for a virtual feature card address getvec: get an interrupt getvec(D3D) 

get page frame number for kernel address hat_^etkpfnum: hat^etkpfnum(D3K) 

virtual address to physical address kvtoph)rs: convert kernel kVtophys(D3D) 

vtop: convert virtual to physical address vtop(D3D) 

bcopy: copy data between address locations in the kernel bcopy(D3DK) 

bpjnapin: allocate virtual address space bp_mapin(D3DK) 

bp_mapout: deallocate virtiial address space bp_mapout(D3DK) 

kvtophys: convert kernel virtual address to physical address kvtophys(D3D) 

adjmsg: trim b5rtes from a message adjmsg(D3DK) 

allocb: allocate a message blodc t.............. allocb(D3DK) 

shared buffer esballoc: allocate a message block using a esballoc(D3DK) 

kernel free memory kmem_zalloc: dlocate and dear space froin kmem__zalloc(D3DK) 

space management map rmaUoc: allocate space from a private rmalloc(D3DK) 

memory kmem_alloc: allocate space from kernel free kmem_alloc(D3DK) 

bp_mapin: allocate virtual address space bp_mapin(D3DK) 

kmem_free: free previously allocated kernel memory kmem_free(D3DK) 

allocb: allocatie a message block allocb(D3DK) 

testb: check for an available buffer testb(D3DK) 

a ftmction when a buffer becomes available bufcall: call bufcall(D3DK) 

call function when buffer is available esbbcall: esbbcall(D3DK) 

behind th^ current queue backq: get pointer to the queue backq(D3DK) 

messages for a specified priority band flushband: flush flushband(D3DK) 

get information about a queue or band of the queue strqget: strqget(D3DK) 

information about a queue or band of the queue /change strqset(D3DK) 

locations in the kernel bcopy: copy data between address bcopy(D3DK) 

call a function when a buffer becomes available bufcall: bufcall(D3DK) 

backq: get pointer to the queue behind the current queue backq(D3DK) 

brelse: return buffer to the bfreelist brelse(D3DK) 

block I/O and wakeup processes biodone: release buffer after biodone(D3DK) 

pending completion of block I/O biowait: suspend processes biowait(D3DK) 

allocb: allocate a message block allocb(D3DK) 

copyb: copy a message block cdpyb(D3DK) 

freeb: free a message block freeb(D3DK) 

rmvb: remove a message block from a message * rmvb(D3DK) 

unlinkb: remove a message block from the head of a message unlinkb(D3DK) 

biodone: release buffer after block I/O and wakeup processes biodone(D3DK) 

buf: block I/O data transfer structure buf(D4DK) 

processes pending completion of block I/O biowait: suspend biowait(D3DK) 

strategy: perform block I/O strategy(D2DK) 

msgb: STREAMS message block structure msgb(D4DK) 

Permuted Index 1 
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esballoc: allocate a message block using a shared buffer esballoc(D3DK) 

spl: block/ allow interrupts spl(D3D) 

linkb: concatenate two message blocks linkb(D3DK) 

address space bp mapin: allocate virtual bp_mapin(D3DK) 

address space bp mapout: deallocate virtual bp_mapout(D3DK) 

manageable imits dma_pageio: break up an I/O request into dma_pageio(D3D) 

bfreelist brelse: return buffer to the brelse(D3DK) 

size in pages (round down) btop: convert size in bytes to btop(D3DK) 

size in pages (round up) btopr: convert size in bytes to * btopr(D3DK) 

structure buf; block I/O data transfer buf(D4DK) 

buffer becomes available bufcall: call a function when a bufcalKDSDK) 

processes biodone: release buffer after block I/O and wakeup biodone(D3DK) 

bufcall: call a function when a buffer becomes available bufcall(D3DK) 

drbuf: erase the contents of a buffer clrbuf(D3DK) 

from a user program to a driver biaffer copyin: copy data copyin(D3DK) 

a message block using a shared buffer esballoc: allocate esballoc(D3DK) 

testb: check for an available buffer testb(D3DK) 

freerbuf: free a raw buffer header freerbuf(D3DK) 

getrbuf: get a raw buffer header getrbuf (D3DK) 

esbbcall: call function when buffer is available esbbcall(D3DK) 

brelse: return buffer to the bfreelist brelse(D3DK) 

drv_usecwait: busy- wait for specified interval drv_usecwait(D3DK) 

memory for a given number of bytes bzero: dear bzero(D3DK) 

convert size in pages to size in bytes ptob: ptob(D3DK) 

adjmsg: trim bytes from a message adjmsg(D3DK) 

msgdsize: return the number of bytes in a message msgdsize(D3DK) 

pullupmsg: concatenate bytes in a message pullupmsg(D3DK) 

down) btop: convert size in bytes to size in pages (roimd btop(D3DK) 

btopr: convert size in bytes to size in pages (roimd up) btopr(D3DK) 

number of bytes bzero: dear memory for a given bzero(D3DK) 

becomes available bufcall: call a function when a buffer .i........^ bufcall(D3DK) 

previous timeout(P3DK) function call imtimeout: cancel untimeout(D3DK) 

available esbbcall: call function when buffer is esbbcall(D3DK) 

function call imtimeout: cancel previous timeout(D3DK) vmtimeout(D3DK) 

vector for a virtual feature card address /get an interrupt getvec(D3D) 

or band of the queue strqset: change information about a queue strqset(D3DK) 

ioctl: control a character device ioctl(D2DK) 

entry point for a non-STREAMS character driver chpoll: poll chpoll(D2DK) 

uwiitec remove a character from a uio structure uwritec(D3DK) 

ureadc: add diaracter to a tdo structure ureadc(D3DK) 

testb: check for an available buffer testb(D3DK) 

mapped device mmap: check virtual mapping for memory mmap(D2K) 

non-STREAMS character driver chpoll: poll entry point for a chpoll(D2DK) 

of bytes bzero: dear memory for a given nimiber bzero(D3DK) 

memory kmem_zalloc: allocate and dear space from kernel free kmem_zalloc(D3DK) 

for a specified nvraiber of dock ticks /process execution delay (D3DK) 

convert microseconds to dock ticks dtvjisectohz: drv__usectohz(D3DK) 
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drvjiztousec convert dock ticks to microseconds drv_hztousec(D3DK) 

device close: relinquish access to a dose(D2DK) 

buffer clrbuf: erase the contents of a clrbuf(D3DK) 

or panic the system cmn err: display an error message cmn_err(D3DK) 

suspend processes pending completion of block I/O biowait: biowait(D3DK) 

pullupmsg: concatenate bytes in a message pullupmsg(D3DK) 

linkb: concatenate two message blodcs linkb(D3DK) 

a driver message on system console print: display print(D2DK) 

clrbuf : erase the contents of a buffer clrbuf (D3DK) 

ioctl: control a character device ioctl(D2DK) 

qband: STREAMS queue flow control information structure qband(D4DK) 

putcti: send a control message to a queue putctl(D3DK) 

parameter to a/ putctll: send a control message with a one-byte putctll(D3DK) 

microseconds drv hztousec: convert dock ticks to drv_hztousec(D3DK) 

internal major number etoimajor: convert external major number to etoimajor(D3D) 

major device nim\ber itoemajor: convert internal to external itoemajor(D3D) 

physical address kvtophys: convert kernel virtual address to kvtophys(D3D) 

ticks drv__usectohz: convert microseconds to dock drv_usectohz(E)3DK) 

structure page_numtopp: convert page frame number to page 

page_nimitopp(D3DK) 

frame number page__pptonum: convert page structure to page page_pptonum(D3DK) 

pages (roimd down) btop: convert size in bytes to size in btop(D3DK) 

pages (round up) btopr: convert size in bytes to size in btopr(D3DK) 

bytes ptob: convert size in pages to size in ptob(D3DK) 

address vtop: convert virtual to physical vtop(D3D) 

copyb: copy a message block copyb(D3DK) 

copymsg: copy a message copymsg(D3DK) 

locations in the kernel bcopy: copy data between address bcopy(D3DK) 

program copyout: copy data from a driver to a xiser copyout(D3DK) 

a driver buff er copyin: copy data from a user program to copyin(D3DK) 

structure uiomove: copy kernel data using uio(E)4DK) uiomove(D3DK) 

copyb: copy a message block copyb(D3DK) 

program to a driver buffer copyin: copy data from a user copyin(D3DK) 

copymsg: copy a message copymsg(D3DK) 

to a iiser program copyout: copy data from a driver copyout(D3DK) 

cred: access credential structure cred(D4DK) 

cred: access credential structure cred(D4DK) 

pointer to the queue behind the current queue backq: get backq(D3DK) 

the kernel bcopy: copy data between address locations in bcopy(D3DK) 

read: read data from a device read(D2DK) 

program copyout: copy data from a driver to a user copyout(D3DK) 

driver buffer copyin: copy data from a user program to a copyin(D3DK) 

test whether a message is a data message datamsg: datamsg(D3DK) 

using uio(D4DK) iovec: data storage structure for I/O • iovec(D4DK) 

datab: STREAMS message data structure datab(D4DK) 

hdedata: hard disk error data structure , , hdedata(D4D) 

write: write data to a device write(D2DK) 
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buf; block I/O data transfer structijre buf(D4DK) 

uiomove: copy kernel data using iiio(D4DK) structure uiomove(D3DK) 

structure datab: STREAMS message data datab(D4DK) 

is a data message datamsg: test whether a message datamsg(D3DK) 

bp mapout: deallocate virtual address space bp_mapout(D3DK) 

streamtab: STREAMS entity declaration structure streamtab(D4DK) 

for a specified number of clock/ delay: delay process execution delay(D3DK) 

specified number of clock/ delay: delay process execution for a delay(D3DK) 

drv_priv: determine driver privilege drv_priv(D3DK) 

dose: relinquish access to a device close(D2DK) 

init: initialize a device init(D2D) 

ioctl: control a character device ioctl(D2DK) 

virtual mapping for memory mapped device mmap: check mmap(D2K) 

open: gain access to a device open(D2DK) 

read: read data from a device * read(D2DK) 

size: return size of logical device , size(D2D) 

start: start access to a device start(D2D) 

write: write data to a device write(D2DK) 

int: process a device interrupt int(D2D) 

segmap: map device memory into user space segmap(D2K) 

getemajor: get external major device ntimber getemajor(D3D) 

geteminor: get external minor device number geteminor(D3D) 

get major or internal major device number getmajor: getmajor(D3DK) 

get minor or internal minor device number getminor: getminor(D3DK) 

internal to external major device number itoemajor: convert itoemajor(D3D) 

and minor makedevice: make device number from external major makedevice(D3DK) 

on a stream in the reverse direction qreply: send a message qreply(D3DK) 

hdedata: hard disk error data structure hdedata(D4D) 

hdelog: log hard disk error hdelog(D3D) 

hdeeqd: initialize hard disk error logging hdeeqd(D3D) 

system console print: display a driver message on print(D2DK) 

the system cmn_err: display an error message or panic cmn_err(D3DK) 

request into manageable imits dma_pageio: break up an I/O dma_pageio(D3D) 

in bytes to size in pages (roimd down) btop: convert size btop(D3DK) 

data from a user program to a driver buffer copyin: copy copyin(D3DK) 

point for a non-STREAMS character driver chpoll: poll entry chpoll(D2DK) 

submit messages to the log driver strlog: strlog(D3DK) 

write queue for this module or driver WR: get pointer to the WR(D3DK) 

value/ module_info: STREAMS driver identification and limit module_info(D4DK) 

print: display a driver message on system console print(D2DK) 

drv_priv: determine driver privilege drv_priv(D3DK) 

copyout: copy data from a driver to a user program copyout(D3DK) 

/structure that specifies a driver's message freeing routine free_rtn(D4DK) 

state information drv_getparm: retrieve kernel drv_getparm(D3DK) 

to microseconds drv hztousec: convert clock ticks drv_hztousec(D3DK) 

privilege drv__priv: determine driver drv_priv(D3DK) 

microseconds to clock ticks drv_usectohz: convert drv_usectohz(D3DK) 



4 



DDI/DKi Reference Manual 



Permuted Index 



specified interval drv iisecwait: busy-wait for drv_usecwait(D3DK) 

dupmsg: duplicate a message dupmsg(D3DK) 

dupmsg: duplicate a message dupmsg(D3DK) 

qenable: enable a queue qenable(D3DK) 

service enableok: reschedule a queue for enableok(D3DK) 

streamtab: STREAMS entity declaration structure streamtab(D4DK) 

character driver chpoll: poll entry point for a non-STREAMS chpoll(D2DK) 

drbuf : erase the contents of a buffer clrbuf (D3DK) 

hdedata: hard disk error data structure hdedata(D4D) 

geterror: return I/O error ; geterror(D3DK) 

hdelog: log hard disk error hdelog(D3D) 

hdeeqd: initialize hard disk error logging hdeeqd(D3D) 

cmn_err: display an error message or panic the system cmn_err(D3DK) 

block using a shared buffer esballoc: allocate a message esballoc(D3DK) 

buffer is available esbbcall: call function when esbbcall(D3DK) 

nimiber to internal major nimiber etoimajor: convert external major etoimajor(D3D) 

activity pending execution of an event sleep: suspend process sleep(D3DK) 

inform a process that an event has occurred poUwakeup: pollwakeup(D3DK) 

specified length of/ timeout: execute a function after a timeout(D3DK) 

wakeup: resume suspended process execution wakeup(D3DK) 

of dock/ delay: delay process execution for a specified number delay(D3DK) 

suspend process activity pending execution of an event sleep: sleep(D3DK) 

/make device number from external major and minor makedevice(D3DK) 

getemajor: get external major device number getemajor(D3D) 

itoemajor: convert internal to external major device number itoemajor(D3D) 

major number etoimajor: convert external major nimiber to internal etpimajor(D3D) 

geteminor: get external minor device number geteminor(D3D) 

an interrupt vector for a virtual feature card address getvec: get getvec(D3D) 

queue qsize: find the nimiber of messages on a ............................. qsize(D3DK) 

rmsetwant: set the map's wait flag for a wakeup rmsetwant(D3DK) 

structure qband: STREAMS queue flow control information" qband(D4DK) 

priority band flushband: flush messages for a specified flushband(D3DK) 

specified priority band flushband: flush messages for a flushband(D3DK) 

queue flushq: remove messages from a flushq(D3DK) 

convert page structure to page frame number page_pptonum: page_pptonimi(D3DK) 

hat_getkpfnum: get page frame nimiber for kernel address hat_£etkpfnum(D3K) 

page_numtopp: convert page frame number to page structure ............... page_numtopp(D3DK) 

freeb: free a message block freeb(D3DK) 

freerbuf: free a raw buffer header , freerbuf(D3DK) 

allocate space from kernel free memory kmem_alloc: kmem_alloc(D3DK) 

and dear space fi:om kernel free memory /allocate kmem_zalloc(D3DK) 

rmwant: wait for free memory rmwant(D3DK) 

memory kmem_free: free previously allocated kernel kmem_free(D3DK) 

space management map rmfree: free space bade into a private rmfree(D3DK) 

freeb: free a message block freeb(D3DK) 

that specifies a driver's message freeing routine /structure free_rtn(D4DK) 

header freerbuf: free a raw buffer freerbuf(D3DK) 
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specifies a driver's message/ free_rtn: structure that free_rtn(I>4DK) 

of time timeout: execute a function after a specified length timeout(D3DK) 

cancel previous timeout(D3DK) function call imtimeout: imtimeout(D3DK) 

available bufcall: call a function when a buffer becomes bufcall(D3DK) 

esbbcall: call function when buffer is available esbbcall(D3DK) 

open: gain access to a device open(D2DK) 

device number getemajor: get external major getemajor(D3D) 

device number geteminor: get external minor geteminor(D3D) 

geterror: return I/O error geterror(D3DK) 

major device number getmajor: get major or internal getmajor(D3DK) 

minor device number getminor: get minor or internal getminor(D3DK) 

queue getq: get the next message from a getq(D3DK) 

getrbuf: get a raw buffer header getrbuf (D3DK) 

for a virtual feature card/ getvec: get an interrupt vector getvec(D3D) 

bzero: dear memory for a given ntimber of b)^es bzero(D3DK) 

hdedata: hard disk error data structure hdedata(D4D) 

hddog: log hard disk error hdelog(D3D) 

hdeeqd: initialize hard disk error logging hdeeqd(D3D) 

number for kernel address hat_^etkpfnum: get page frame hat_getkpfnum(D3K) 

structure hdedata: hard disk error data hdedata(D4D) 

error logging hdeeqd: initialize hard disk hdeeqd(D3D) 

hdelog: log hard disk error hdelog(D3D) 

remove a message block from the head of a message unlinkb: unlinkb(D3DK) 

putbq: place a message at the head of a queue putbq(D3DK) 

freerbuf: free a raw buffer header freerbuf (D3DK) 

getrbuf: get a raw buffer header getrbuf (D3DK) 

module info: STREAMS driver identification and limit value/ module_info(D4DK) 

has occurred pollwakeup: inform a process that an event pollwakeup(D3DK) 

of the queue strqget: get information about a queue or band strqget(D3DK) 

of the queue strqset: change information about a queue or band strqset(D3DK) 

retrieve kernd state information drv_getparm: drv_getparm(D3DK) 

qband: STREAMS queue fiow control information structure qband(D4DK) 

init: initialize a device init(D2D) 

init: initialize a device init(D2D) 

management map rminit: initialize a private space rminit(D3DK) 

logging hdeeqd: initialize hard disk error hdeeqd(D3D) 

insq: insert a message into a queue insq(D3DK) 

queue insq: insert a message into a insq(D3DK) 

int: process a device interrupt int(D2D) 

max: return the larger of two integers max(D3DK) 

min: return the lesser of two integers min(D3DK) 

getmajor: get major or internal major device number getmajor(D3DK) 

convert external major number to internal major nimiber etoimajor: etoimajor(D3D) 

getminor: get minor or internal minor device number getminor(D3DK) 

number itoemajor: convert internal to external major device itoemajor(D3D) 

int: process a device interrupt int(D2D) 

feature card/ getvec: get an interrupt vector for a virtual getvec(D3D) 
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spl: block/allow interrupts spl(D3D) 

busy-wait for specified interval drv_usecwait: drv_usecwait(D3DK) 

/release buffer after block I/O and wakeup processes biodone(D3DK) 

buf: block I/O data transfer structure buf(D4DK) 

geterror: return I/O error geterror(D3DK) 

pending completion of block I/O biowait: suspend processes biowait(D3DK) 

strategy: perform block I/O strategy(D2DK) 

physiock: validate and issue raw I/O request physiock(D3D) 

dma^pageio: break up an I/O request into manageable units dma_pageio(D3D) 

uio: scatter /gather I/O request structure uio(D4DK) 

iovec: data storage structure for I/O using uioG>4DK) iovec(D4DK) 

ioctl: control a character device ioctl(D2DK) 

I/O using uio(D4DK) iovec data storage structure for iovec(D4DK) 

physiock: validate and issue raw I/O request physiock(D3D) 

external major device number itoemajor: convert internal to itoemajor(D3D) 

get page frame number for kernel address hat_getkpfniim: hat_^etkpfnim\(D3K) 

structure uiomove: copy kernel data using uio(I>4DK) uiomove(D3DK) 

between address locations in the kernel bcopy: copy data bcopy(D3DK) 

kmem_alloc: allocate space from kernel free memory kmem_aIloc(D3DK) 

allocate and dear space from kernel free memory kmem zalloc: kmem_zalloc(D3DK) 

free previously allocated kernel memory kmem_free: kmem_free(D3DK) 

drv__getparm: retrieve kernel state information drv__getparm(D3DK) 

physical/ kvtophys: convert kernel virtual address to kvtophys(D3D) 

kernel free memory kmem_alloc: allocate space from kmem_alloc(D3DK) 

allocated kernel memory kmem_free: free previously kmem_free(D3DK) 

space from kernel free memory kmem zalloc: allocate and dear kmem_zalloc(D3DK) 

address to physical address kvtophys: convert kernel virtual kvtophys(D3D) 

max: return the larger of two integers max(D3DK) 

a function after a specified length of time timeout: execute timeout(D3DK) 

min: return the lesser of two integers min(D3DK) 

/STREAMS driver identification and limit value structure module_info(D4DK) 

blocks linkb: concatenate two message linkb(D3DK) 

bcopy: copy data between address locations in the kernel bcopy(D3DK) 

strlog: submit messages to the log driver strlog(D3DK) 

hdelog: log hard disk error hdelog(D3D) 

initialize hard disk error logging hdeeqd: hdeeqd(D3D) 

size: return size of logical device size(D2D) 

make device number from external major and minor makedevice: makedevice(D3DK) 

getemajor: get external major device number getemajor(D3D) 

getmajor: get major or internal major device number getmajor(D3DK) 

convert internal to external major device number itoemajor: itoemajor(D3D) 

external major number to internal major number etoimajor: convert etoimajor(D3D) 

etoimajor: convert external major number to internal major/ etoimajor(D3D) 

nimiber getmajor: get major or internal major device getmajor(D3DK) 

from external major and minor makedevice: make device number makedevice(D3DK) 

break up an I/O request into manageable imits dma_pageio: dma_pageio(D3D) 

space from a private space management map rmalloc: allocate rmalloc(D3DK) 
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space back into a private space management map rmfree: free rmfree(D3DK) 

initialize a private space management map nninit: nninit(D3DK) 

segmap: map device memory into user space segmap(D2K) 

from a private space management map rmalloc: allocate space rmalloc(D3DK) 

into a private space management map rmfree: free space back rmfree(D3DK) 

a private space management map rminit: initialize rminit(D3DK) 

map: private memory map structure map(D4DK) 

map: private memory map structure map(D4DK) 

check virtual mapping for memory mapped device mmap: mmap(D2K) 

mmap: check virtual mapping for memory mapped device mmap(D2K) 

rmsetwant: set the map's wait flag for a wakeup rmsetwant(D3DK) 

integers max: return the larger of two max(D3DK) 

allocate space from kernel free memory kmem_alloc: kmem_alloc(D3DK) 

free previously allocated kernel memory kmem free: kmem_free(D3DK) 

and clear space from kernel free memory kmem zalloc: allocate kmem_zalloc(D3DK) 

rmwant: wait for free memory rmwant(D3DK) 

verify whether user has access to memory useracc: useracc(D3DK) 

bytes bzero: dear memory for a given nimiber of bzero(D3DK) 

segmap: map device memory into user space segmap(D2K) 

map: private memory map structure map(D4DK) 

mmap: check virtual mapping for memory mapped device mmap(D2K) 

putbq: place a message at the head of a queue putbq(D3DK) 

allocb: allocate a message block allocb(D3DK) 

copyb: copy a message block copyb(D3DK) 

freeb: free a message block freeb(D3DK) 

rmvb: remove a message block from a message rmvb(D3DK) 

message tinlinkb: remove a message block from the head of a imlinkb(D3DK) 

msgb: STREAMS message block structure msgb(D4DK) 

buffer esballoc allocate a message block using a shared esbaIloc(D3DK) 

linkb: concatenate two message blocks linkb(D3DK) 

datab: STREAMS message data struchire datab(D4DK) 

adjmsg: trim bytes from a message adjmsg(D3DK) 

copymsg: copy a message copymsg(D3DK) 

test whether a message is a data message datamsg: datamsg(D3DK) 

dupmsg: duplicate a message dupmsg(D3DK) 

return the nimiber of bytes in a message msgdsize: „ msgdsize(D3DK) 

pullupmsg: concatenate bytes in a message pullupmsg(D3DK) 

remove a message block from a message rmvb: rmvb(D3DK) 

message block from the head of a message imlinkb: remove a imlinkb(D3DK) 

/that specifies a driver's message freeing routine freej:tn(I>4DK) 

getq: get the next message from a queue getq(D3DK) 

rmvq: remove a message from a queue rmvq(D3DK) 

insq: insert a message into a queue insq(D3DK) 

datamsg: test whether a message is a data message datamsg(D3DK) 

putq: put a message on a queue putq(D3DK) 

reverse direction qreply: send a message on a stream in the qreply(D3DK) 

print: display a driver message on system console print(D2DK) 
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cmn^err: display an error message or panic the system cmn_err(D3DK) 

putctl: send a control message to a queue putctl(D3DK) 

putnext: send a message to the next queue putnext(D3DK) 

to a/ putctll: send a control message with a one-byte parameter putctll(D3DK) 

srv: service queued messages srv(D2DK) 

band flushband: flush messages for a specified priority flushband(D3DK) 

flushq: remove messages from a queue flushq(D3DK) 

put: receive messages from the preceding queue put(D2DK) 

qsize: find the number of messages on a queue qsize(D3DK) 

strlog: submit messages to the log driver strlog(D3DK) 

convert dock ticks to microseconds drv hztousec: drv_hztousec(D3DK) 

drvjisectohz: convert microseconds to clock ticks drv_tisectohz(D3DK) 

integers min: return the lesser of two min(D3DK) 

geteminor: get external minor device number geteminor(D3D) 

getminor: get minor or internal minor device nimiber getminor(D3DK) 

nimiber from external major and minor makedevice: make device makedevice(D3DK) 

number getminor: get minor or internal minor device getminor(D3DK) 

memory mapped device mmap: check virtual mapping for mmap(D2K) 

to the write queue for this module or driver VVR: get pointer WR(D3Dk) 

identification and limit value/ module_info: STREAMS driver module_info(D4DK) 

structure msgb: STREAMS message block msgb(D4DK) 

bytes in a message msgdsize: return the nimiber of msgdsize(D3DK) 

getq: get the next message from a queue getq(D3DK) 

putnext: send a message to the next queue putnext(D3DK) 

SAMESTR: test if next queue is same type SAMESTR(D3DK) 

bdng scheduled noenable: prevent a queue from noenable(D3DK) 

chpoll: poll entry point for a non-STREAMS character driver chpoll(D2DK) 

major number to internal major nimiber /convert external etoimajor(D3D) 

get external major device number geteinajor: getemajor(D3D) 

get external minor device number geteminor: geteminor(D3D) 

major or internal major device number getmajor: get getmajor(D3DK) 

minor or internal minor device number getminor: get getminor(D3DK) 

internal to external major device number itoemajor: convert itoemajor(D3D) 

page structure to page frame number page_pptonum: convert page_pptonum(D3DK) 

hat getkpfnum: get page frame nimiber for kernel address hat_^etkpfnum(D3K) 

minor makedevice: make device number from external major and makedevice(D3DK) 

bzero: dear memory for a given number of bytes bzero(D3DK) 

msgdsize: return the number of b5rtes in a message msgdsize(D3DK) 

process execution for a specified number of dock ticks /delay ,. delay(D3DK) 

qsize: find the number of messages on a queue qsize(D3DK) 

etoimajor: convert external major number to internal major number etoimajor(D3D) 

page_numtopp: convert page frame number to page structure page_numtopp(D3DK) 

a process that an event has occurred poUwakeup: inform pollwakeup(D3DK) 

/send a control message with a one-byte parameter to a queue putctll (D3DK) 

open: gain access to a device open(D2DK) 

partner queue OTHERQ: get pointer to queue's OTHERQ(D3DK) 
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convert page structure to page frame number page_pptonum: 

page__pptonum(D3DK) 

address hat_getkpfnvtm: get page frame nimiber for kernel hat_getkpfnimi(D3K) 

structure page_nim\topp: convert page frame number to page page_numtopp(D3DK) 

convert page frame nvimber to page structure page_numtopp: page_nim\topp(D3DK) 

nvimber page^pptonimi: convert page structure to page frame page_pptonum(D3DK) 

number to page structure page_numtopp: convert page frame 

page_numtopp(D3DK) 

structure to page frame number page__pptonum: convert page page_pptonum(D3DK) 

convert size in bytes to size in pages (round down) btop: btop(D3DK) 

convert size in bytes to size in pages (round up) btopr: btopr(D3DK) 

ptob: convert size in pages to size in bytes ptob(D3DK) 

display an error message or panic the system cmn_err: cmn_err(D3DK) 

a control message with a one-byte parameter to a queue /send putctll(D3DK) 

OTHERQ: get pointer to queue's partner queue OTHERQ(D3DK) 

biowait: suspend processes pending completion of block I/O biowait(D3DK) 

sleep: suspend process activity pending execution of an event sleep(D3DK) 

strategy: perform block I/O strategy(D2DK) 

convert kernel virtual address to physical address kvtophys: kvtophys(D3D) 

vtop: convert virtual to physical address vtop(D3D) 

I/O request physiock: validate and issue raw physiock(D3D) 

queue putbq: place a message at the head of a putbq(D3DK) 

driver chpoU: poll entry point for a non-STREAMS character chpoll(D2DK) 

OTHERQ: get pointer to queue's partner queue OTHERQ(D3DK) 

current queue backq: get pointer to the queue behind the backq(D3DK) 

RD: get pointer to the read queue RD(D3DK) 

this module or driver WR: get pointer to the write queue for WR(D3DK) 

non-STREAMS character/ chpoll: poll entry point for a chpoll(D2DK) 

an event has occurred pollwakeup: inform a process that pollwakeup(D3DK) 

put: receive messages from the preceding queue put(D2DK) 

scheduled noenable: prevent a queue from being noenable(D3DK) 

call untimeout: cancel previous timeout(D3DK) function untimeout(D3DK) 

memory kmem_free: free previously allocated kernel kmem_free(D3DK) 

on system console print: display a driver message print(D2DK) 

flush messages for a specified priority band flushband: flushband(D3DK) 

map: private memory map structure map(D4DK) 

rmalloc: allocate space from a private space management map rmalloc(D3DK) 

rmfree: free space back into a private space management map , rmfree(D3DK) 

rminit: initialize a private space management map rminit(D3DK) 

drv_priv: determine driver privilege drv_priv(D3DK) 

qbiit: STREAMS queue processing procedures structure qinit(D4DK) 

int: process a device interrupt int(D2D) 

execution of an/ sleep: suspend process activity pending sleep(D3DK) 

wakeup: resume suspended process execution wakeup(D3DK) 

number of dock/ delay: delay process execution for a specified delay(D3DK) 

occurred pollwakeup: inform a process that an event has pollwakeup(D3DK) 

buffer after block I/O and wakeup processes biodone: release biodone(D3Dk) 
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block I/O biowait: suspend processes pending completion of biowait(D3DK) 

cpnit: STREAMS queue processing procedures structure qinit(D4DK) 

copy data from a driver to a user program copyout: copyout(D3DK) 

copyin: copy data from a user program to a driver buffer copyin(D3DK) 

size in bytes ptob: convert size in pages to ptob(D3DK) 

message ptillupmsg: concatenate bytes iii a pullupmsg(D3DK) 

putq: put a message on a queue putq(D3DK) 

preceding queue put: receive messages from the put(D2DK) 

head of a queue putbq: place a message at the putbq(D3DK) 

a queue putctl: send a control message to putctl(D3DK) 

with a one-byte parameter to a/ putctll: send a control message putctll(D3DK) 

next queue putnext: send a message to the putnext(D3DK) 

putq: put a message on a queue putq(D3DK) 

information structure qband: STREAMS queue flow control qband(D4DK) 

qenable: enable a queue qenable(D3DK) 

procedures structure ^it: STREAMS queue processing qinit(D4DK) 

stream in the reverse direction qpreply: send a message on a qreply(D3DK) 

messages on a queue qsize: find the nimiber of * qsize(D3i)K) 

backq: get pointer to the queue behind the current queue backq(D3E)K) 

to the queue behind the current queue backq: get pointer backq(D3DK) 

flushq: remove messages from a queue flushq(D3DK) 

getq: get the next message from a queue getq(D3DK) 

insq: insert a message into a queue insq(D3DK) 

get pointer to queue's partner queue OTHERQ: OTHERQ(D3DK) 

place a message at the head of a queue putbq: putbq(D3DK) 

with a one-byte parameter to a queue /send a control message putctil(D3DK) 

send a control message to a queue putcti: putcti(D3DK) 

messages from the preceding queue put: receive put(D2DK) 

send a message to the next queue putnext: putnext(D3DK) 

putq: put a message on a queue putq(D3DK) 

qenable: enable a queue qenable(D3DK) 

find the number of messages on a queue qsize: qsize(D3DK) 

RD: get pointer to the read queue RD(D3DK) 

rmvq: remove a message from a queue rmvq(D3DK) 

about a queue or band of the queue strqget: get information strqget(D3DK) 

about a queue or band of the queue /change information strqset(D3DK) 

structure qband: STREAMS queue flow control information qband(D4DK) 

enableok: reschedule a queue for service enableok(D3DK) 

WR: get pointer to the write queue for this module or driver WR(D3DK) 

noenable: prevent a queue from being scheduled noenable(D3DK) 

SAMESTR: test if next queue is same type SAMESTR(D3DK) 

strqget: get information about a queue or band of the queue strqget(D3DK) 

/change information about a queue or band of the queue strqset(D3DK) 

structure qinit: STREAMS queue processing procediires qinit(D4DK) 

queue: STREAMS queue structure queue(D4DK) 

queue: STREAMS queue structure queue(D4DK) 

srv: service queued messages srv(D2DK) 
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OTHERQ: get pointer to queue's partner queue OTHERQ(D3DK) 

freerbuf : free a raw buffer header freerbuf(D3DK) 

getrbuf : get a raw buffer header getrbuf(D3DK) 

physiodc validate and issue raw I/O request physiock(D3D) 

RD: get pointer to the read queue RD(D3DK) 

read: read data from a device read(D2DK) 

RD; get pointer to the read queue RD(D3DK) 

read: read data from a device read(D2DK) 

preceding queue put receive messages from the pUt(D2DK) 

and wakeup processes biodone: release buffer after block I/O biodone(D3DK) 

dose: relinquish access to a device close(D2DK) 

structure uwritec: remove a character from a uio uwritec(D3DK) 

message rmvb: remove a message block from a rmvb(D3DK) 

head of a message unlinkb: remove a message block from the unlinkb(D3DK) 

rmvq: remove a message from a queue rmvq(D3DK) 

flushq: remove messages from a queue flushq(D3DK) 

validate and issue raw I/O request physiock: physiock(D3D) 

dmajpageio: break up an I/O request into manageable units dma_pageio(D3D) 

uio: scatter/gather I/O request structure uio(D4DK) 

enableok: reschedule a queue for service enableok(D3DK) 

execution wakeup: resume suspended process wakeup(D3DK) 

drv getparm: retrieve kernel state information drv_getparm(D3DK) 

brelse: return buffer to the bfreelist brelse(D3DK) 

geterror: return I/O error geterror(D3DK) 

size: return size of logical device size(D2D) 

max: return the larger of two integers max(D3DK) 

min: return the lesser of two integers min(D3DK) 

message msgdsize: return the nimtber of , bytes in a msgdsize(D3DK) 

send a message on a stream in the reverse direction qreply: , qreply(D3DK) 

private space management map rmalloc allocate space from a rmalloc(D3DK) 

private space management map rmfree: free space back into a rmfree(D3DK) 

space management map rminit: initialize a private rminit(D3DK) 

flag for a wakeup rmsetwant: set the map's wait rmsetwant(D3DK) 

a message rmvb: remove a message block from rmvb(D3DK) 

queue rmvq: remove a message from a rmvq(D3DK) 

rmwant: wait for free memory rmwant(D3DK) 

size in bytes to size in pages (round down) btop: convert btop(D3DK) 

size in bytes to size in pages (round up) btopr: convert btopr(D3DK) 

a driver's message freeing routine /structure that specifies free_rtn(D4DK) 

same type SAMESTR: test if next queue is SAMESTR(D3DK) 

structure mo: scatter/gather I/O request uio(D4DK) 

prevent a queue from being scheduled noenable: noenable(D3DK) 

user space segmap: map device memory into segmap(D2K) 

putctl: send a control message to a queue putctl(D3DK) 

one-byte parameter to a/ putctll: send a control message with a putctll(D3DK) 

reverse direction qreply: send a message on a stream in the qreply(D3DK) 

putnext: send a message to the next queue putnext(D3DK) 
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enableok reschedule a queue for service enableok(D3DK) 

srv: service queued messages srv(D2DK) 

wakeup rmsetwant: set the map's wait flag for a rmsetwant(D3DK) 

allocate a message block using a shared buffer esballoc: esballoc(D3DK) 

ptob: convert size in pages to size in bytes ptob(D3DK) 

(round down) btop: convert size in bytes to size in pages btop(D3DK) 

(round up) btopr: convert size in b5rtes to size in pages btopr(D3DK) 

btop: convert size in bytes to size in pages (roimd down) btop(D3DK) 

btopr: convert size in bytes to size in pages (round up) btopr(D3DK) 

ptob: convert size in pages to size in bytes ptob(D3DK) 

size: return size of logical device size(D2D) 

device size: return size of logical size(D2D) 

pending execution of an event sleep: suspend process activity sleep(D3DK) 

management map rmfree: free space back into a private space rmfree(D3DK) 

allocate virtual address space bp_mapin: bp_mapin(D3DK) 

deallocate virtual address space bp_mapout: bp_mapout(D3DK) 

map device memory into user space segmap: segmap(D2K) 

management map rmalloc: allocate space from a private space rmalloc(D3DK) 

kmem_alloc: allocate space from kernel free memory kmem_alloc(D3DK) 

kmem zalloc: allocate and dear space from kernel free memory kmem_zaUoc(D3DK) 

allocate space from a private space management map rmalloc: rmalloc(D3DK) 

free space back into a private space management map rmfree: rmfree(D3DK) 

rminit: initialize a private space management map rminit(D3DK) 

drv_usecwait: busy-wait for specified interval drv_usecwait(D3DK) 

/execute a fvmction after a specified length of time timeout(D3DK) 

/delay process execution for a specified nimiber of dock ticks delay(D3DK) 

flushband: flush messages for a specified priority band flushband(D3DK) 

freeing/ free_rtn: structure that specifies a driver's message freejrtn(D4DK) 

spl: block/ allow interrupts spl(D3D) 

srv: service queued messages srv(D2DK) 

start: start access to a device , start(D2D) 

start: start access to a device start(D2D) 

uio(D4DK) iovec data storage structure for I/O using iovec(D4DK) 

strategy: perform block I/O strategy (D2DK) 

qreply: send a message on a stream in the reverse direction qreply(D3DK) 

limit value/ module_info: STREAMS driver identification and module Jnfo(D4DK) 

structure streamtab: STREAMS entity dedaration streamtab(D4DK) 

msgb: STREAMS message block strudure msgb(D4DK) 

datab: STREAMS message data strudure datab(D4DK) 

information structure qband: STREAMS queue flow control qband(D4DK) 

procedures structure qinit: STREAMS queue processing qinit(D4DK) 

queue: STREAMS queue structure queue(D4DK) 

dedaration structure streamtab: STREAMS entity streamtab(D4DK) 

log driver strlog: subnut messages to the strlog(D3DK) 

queue or band of the queue strqget: get information about a strqget(D3DK) 

a queue or band of the queue strqset: change information about strqset(D3DK) 

biif: block I/O data transfer structure buf(D4DK) 
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cred: access credential structure cred(D4DK) 

datab: STREAMS message data structure datab(D4DK) 

hdedata: hard disk error data structure hdedata(D4D) 

map: private memory map structure map(D4DK) 

identification and limit value structure /STREAMS driver module_info(D4DK) 

msgb; STREAMS message block structure msgb(D4DK) 

convert page frame number to page structure page_numtopp: page__numtopp(D3DK) 

queue flow control information structure qband: STREAMS qband(D4DK) 

queue processing procedures structure cpiut: STREAMS (pnit(D4DK) 

queue: STREAMS queue structure queue(D4DK) 

STREAMS entity declaration structure streamtab: streamtab(D4DK) 

uio: scatter/gather I/O request structiare uio(D4DK) 

copy kernel data iising uio(D4DK) structure uiomove: uiomove(D3DK) 

ureadc: add character to a uio structure ureadc(D3DK) 

remove a character from a uio structure uwritec: uwritec(D3DK) 

iovec: data storage structure for I/O using uio(D4DK) iovec(D4DK) 

driver's message/ free_rtn: structure that specifies a free_rtn(D4DK) 

page__pptonum: convert page structure to page frame number page_pptonim\(D3DK) 

strlog: submit messages to the log driver strlog(D3DK) 

execution of an event sleep: suspend process activity pending sleep(D3DK) 

completion of block I/O biowait: suspend processes pending biowait(D3DK) 

wakeup: resiraie suspended process execution wakeup(D3DK) 

display a driver message on system console print: print(D2DK) 

an error message or panic the system cmn_err: display cmn_err(D3DK) 

SAMESTR: test if next queue is same type SAMESTR(D3DK) 

message datamsg: test whether a message is a data datamsg(D3DK) 

buffer testb: check for an available testb(D3DK) 

for a specified number of clock ticks /delay process execution delay(D3DK) 

convert microseconds to dock ticks drv_usectohz: drv_usectohz(D3DK) 

drvjiztousec: convert dock ticks to miaoseconds drv_hztousec(D3DK) 

a specified length of time timeout: execute a function after timeout(D3DK) 

tmtimeout: cancel previous timeout(D3DK) function call untimeout(D3DK) 

buf: block I/O data transfer structure buf(D4DK) 

adjmsg: trim bytes from a message adjmsg(D3DK) 

test if next queue is same type SAMESTR: SAMESTR(D3DK) 

structure uio: scatter/gather I/O request uio(D4DK) 

iireadc: add character to a uio structure ureadc(D3DK) 

remove a character from a uio structure uwritec: uwritec(D3DK) 

storage structure for I/O using uio(D4DK) iovec data iovec(D4DK) 

uiomove: copy kernel data using uio(D4DK) structure uiomove(D3DK) 

uio(D4DK) structure uiomove: copy kernel data using uiomove(D3DK) 

up an I/O request into manageable imits dma_pageio: break dma_pageio(D3D) 

from the head of a message imlinkb: remove a message block imlinkb(D3DK) 

timeout(D3DK) function call vmtimeout: cancel previous imtimeout(D3DK) 

in bytes to size in pages (round up) btopr: convert size btopr(D3DK) 

structure ureadc: add character to a laio ureadc(D3DK) 

useracc verify whether user has access to memory useracc(D3DK) 
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copy data from a driver to a user program copyout: copyout(D3DK) 

copyin: copy data from a user program to a driver buffer copyir\(D3DK) 

segmap: map device memory into user space segmap(D2K) 

access to memory useracc verify whether user has useracc(D3DK) 

allocate a message blodc using a shared buffer esballoc: esballoc(D3DK) 

data storage structure for I/O using uio(D4DK) iovec: iovec(D4DK) 

uiomove: copy kernel data using uio(D4DK) structure uiomove(D3DK) 

a uio structure uwritec: remove a character from uwritec(D3DK) 

request physiock: validate and issue raw I/O physiock(D3D) 

driver identification and limit value structure /STREAMS module_info(D4DK) 

address getvec: get an interrupt vector for a virtual feature card getvec(D3D) 

memory useracc: verify whether user has access to useracc(D3DK) 

bp_mapin: allocate virtual address space bp_mapin(D3DK) 

bpjnapout: deallocate virtual address space bp_mapout(D3DK) 

address kvtophys: convert kernel virtual address to physical kvtophys(D3D) 

/get an interrupt vector for a virtual feature card address getvec(D3D) 

device mmap: check virtual mapping for memory mapped mmap(D2K) 

vtop: convert virtual to physical address vtop(D3D) 

address vtop: convert virtual to physical vtop(D3D) 

rmsetwant: set the map's wait flag for a wakeup rmsetwant(D3DK) 

rmwant: wait for free memory rmwant(D3DK) 

set the map's wait flag for a wakeup rmsetwant: rmsetwant(D3DK) 

buffer after block I/O and wakeup processes /release biodone(D3DK) 

execution wakeup: resimte suspended process wakeup(D3DK) 

message datamsg: test whether a message is a data datamsg(D3DK) 

useracc: verify whether user has access to memory useracc(D3DK) 

queue for this modiile or driver WR: get pointer to the write WR(D3DK) 

write: write data to a device write(D2DK) 

driver WR: get pointer to the write queue for this module or WR(D3DK) 

write: write data to a device write(D2DK) 
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